@@ -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** | | | | |
+| `post_api_keys` | 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=python#postapikeys) | Use IAM authentication |
+| `put_cloudant_security_configuration` | Modify only Cloudant related database permissions | `PUT /_api/v2/db/{db}/_security` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#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** | | | | |
+`get_activity_tracker_events` | Retrieve activity tracking events information | `GET /_api/v2/user/activity_tracker/events` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#getactivitytrackerevents) | `management` events are always enabled, `data` events are not currently available in Gen 2 |
+`post_activity_tracker_events` | Modify activity tracking events configuration | `POST /_api/v2/user/activity_tracker/events` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#postactivitytrackerevents) | `management` events are always enabled, `data` events are not currently available in Gen 2 |
+| **CORS configuration** | | | | |
+| `get_cors_information` | Retrieve CORS configuration information | `GET /_api/v2/user/config/cors` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#getcorsinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| `put_cors_configuration` | Modify CORS configuration | `PUT /_api/v2/user/config/cors` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#putcorsconfiguration) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| **Capacity configuration** | | | | |
+| `get_capacity_databases_information` | Retrieve maximum allowed database count | `GET /_api/v2/user/capacity/databases` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#getcapacitydatabasesinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| `get_capacity_throughput_information` | Retrieve provisioned throughput capacity information | `GET /_api/v2/user/capacity/throughput` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#getcapacitythroughputinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| `put_capacity_throughput_configuration` | Update the target provisioned throughput capacity | `PUT /_api/v2/user/capacity/throughput` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#putcapacitythroughputconfiguration) | Use the [Platform Services SDK](#using-the-platform-services-sdk)
+| **Capacity monitoring** | | | | |
+| `get_current_databases_information` | Retrieve current database count | `GET /_api/v2/user/current/databases` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=python#getcurrentdatabasesinformation) | Use the length of the list returned from the `get_all_dbs` operation.
+| `get_current_throughput_information` | 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=python#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 Python SDK](https://github.com/IBM/platform-services-python-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=python#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=python#create-resource-instance).
+For a pre-existing instance use [Update a resource instance](https://cloud.ibm.com/apidocs/resource-controller/resource-controller?code=python#update-resource-instance).
+
+
 ### Path elements containing the `+` character
 
 Path elements containing the `+` character in the SDKs are not interoperable with:
 
@@ -59,7 +59,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-python-sdk/tree/v0.11.8/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.