docs(generated): Gen 2 compatibility notes

Generated SDK source code using:
- Generator version 3.114.4
- Specification version 1.0.0-dev0.1.39
- Automation (cloudant-sdks) version d586e4c

Author: cloudant-sdks-automation

KNOWN_ISSUES.md

@@ -2,6 +2,60 @@
 
 ## All Cloudant SDKs
 
+### Cloudant (Gen 2) Compatibility
+
+Cloudant Gen 2 is compatible with IAM authentication only.
+The SDK authentication types `BASIC` and `COUCHDB_SESSION` do not work with Cloudant Gen 2 instances.
+
+Instances of Cloudant Gen 2 do not provide some configuration and monitoring APIs that were available in Gen 1.
+
+Migrating an application using this SDK from Cloudant Gen 1 to Cloudant Gen 2 requires either removing calls to these operations
+or replacing them with alternatives.
+
+This table summarizes the SDK operations that are incompatible with Cloudant Gen 2 instances and the recommended replacement operations.
+
+| Gen 1 operation | Summary | Gen 1 Endpoint | API docs link | Replacement operation for Gen 2 |
+|---|---|---|---|---|
+| **Authentication and authorization** | | | | |
+| `postApiKeys` | Generates API keys for apps or persons to enable database access | `POST /_api/v2/api_keys` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#postapikeys) | Use IAM authentication |
+| `putCloudantSecurityConfiguration` | Modify only Cloudant related database permissions | `PUT /_api/v2/db/{db}/_security` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#putcloudantsecurity) | Use [database level IAM policies](https://cloud.ibm.com/docs/cloudant-gen2?topic=cloudant-gen2-managing-access-for-cloudant#database-level-iam-policies) |
+| **Audit events configuration** | | | | |
+`getActivityTrackerEvents` | Retrieve activity tracking events information | `GET /_api/v2/user/activity_tracker/events` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getactivitytrackerevents) | `management` events are always enabled, `data` events are not currently available in Gen 2 |
+`postActivityTrackerEvents` | Modify activity tracking events configuration | `POST /_api/v2/user/activity_tracker/events` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#postactivitytrackerevents) | `management` events are always enabled, `data` events are not currently available in Gen 2 |
+| **CORS configuration** | | | | |
+| `getCorsInformation` | Retrieve CORS configuration information | `GET /_api/v2/user/config/cors` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcorsinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| `putCorsConfiguration` | Modify CORS configuration | `PUT /_api/v2/user/config/cors` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#putcorsconfiguration) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| **Capacity configuration** | | | | |
+| `getCapacityDatabasesInformation` | Retrieve maximum allowed database count | `GET /_api/v2/user/capacity/databases` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcapacitydatabasesinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| `getCapacityThroughputInformation` | Retrieve provisioned throughput capacity information | `GET /_api/v2/user/capacity/throughput` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcapacitythroughputinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| `putCapacityThroughputConfiguration` | Update the target provisioned throughput capacity | `PUT /_api/v2/user/capacity/throughput` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#putcapacitythroughputconfiguration) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| **Capacity monitoring** | | | | |
+| `getCurrentDatabasesInformation` | Retrieve current database count | `GET /_api/v2/user/current/databases` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcurrentdatabasesinformation) | Use the length of the list returned from the `getAllDbs` operation.
+| `getCurrentThroughputInformation` | Retrieve the current provisioned throughput capacity consumption | `GET /_api/v2/user/current/throughput` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcurrentthroughputinformation) | Use a Prometheus instant query with IBM Cloud Monitoring APIs. For example to get the capacity consumption rate over the last minute use a query like `rate(ibm_cloudant_permitted_operations_total[1m])`. See the [IBM Cloud Monitoring docs for an example](https://cloud.ibm.com/docs/monitoring?topic=monitoring-metrics_api#metrics-api-sample-prom).
+
+#### Using the Platform Services SDK
+
+Use the [IBM Cloud Platform Services Java SDK](https://github.com/IBM/platform-services-java-sdk) Resource Controller APIs to programmatically configure your Cloudant Gen 2 instance.
+
+Update the configuration values in the `parameters` mapping of key-value pairs.
+Read the current values from the `extensions` mapping of key-value pairs.
+
+| Key path in `parameters` or `extensions` | Value description |
+| --- | --- |
+`dataservices.cloudant.capacity_units` | The provisioned throughput capacity of the instance in [units](https://cloud.ibm.com/docs/cloudant-gen2?topic=cloudant-gen2-usage-and-charges#provisioned-throughput-capacity-units)
+`dataservices.cloudant.configuration.cors` | The CORS configuration object of the instance with booleans for `enabled` and `allowCredentials` and a string array of `origins`
+`dataservices.cloudant.configuration.db_count_limit` | Read only value of the maximum number of databases allowed on the instance
+
+##### Viewing configuration
+
+Use [Get a resource instance](https://cloud.ibm.com/apidocs/resource-controller/resource-controller?code=java#get-resource-instance) to retrieve the resource instance configuration.
+
+##### Modifying configuration
+
+For a new instance use [Create (provision) a new resource instance](https://cloud.ibm.com/apidocs/resource-controller/resource-controller?code=java#create-resource-instance).
+For a pre-existing instance use [Update a resource instance](https://cloud.ibm.com/apidocs/resource-controller/resource-controller?code=java#update-resource-instance).
+
+
 ### Path elements containing the `+` character
 
 Path elements containing the `+` character in the SDKs are not interoperable with:

README.md

@@ -60,7 +60,8 @@ project:
 
 - Supported by IBM Cloudant.
 - Server compatibility with:
-  - IBM Cloudant.
+  - IBM Cloudant (Gen 1).
+  - IBM Cloudant (Gen 2) - see [compatibility notes](https://github.com/IBM/cloudant-java-sdk/tree/v0.10.19/KNOWN_ISSUES.md#cloudant-gen-2-compatibility).
   - [Apache CouchDB 3.x](https://docs.couchdb.org/en/stable/) for data operations.
 - Includes all the most popular and latest supported endpoints for
   applications.