Migrate to Confluent CLI v2

Until today, we’ve had separate CLI clients for managing Confluent Cloud (ccloud) and Confluent Platform (confluent).

The second major version of the Confluent CLI, confluent v2.0, allows you to manage both Confluent Cloud and Confluent Platform from the same CLI client.

ccloud will be sunset on May 9, 2022, and new functionality will appear in the unified confluent client.

As with prior CLI versions, you must authenticate against a specific deployment before you can execute management commands.

  • To manage a Confluent Cloud deployment, run the following command which is comparable to what you did with the old ccloud client:

    confluent login
    
  • To manage a Confluent Platform deployment, run the following command just as you did with the preceding confluent v1.x client:

    confluent login --url <Metadata service URL>
    

The functionality of confluent v2.0 is determined by whether you are logged in to a Confluent Cloud or Confluent Platform deployment.

Below is a description of the breaking changes included in this release, as well as directions for how you can update to confluent v2.0 from an existing Confluent CLI. Accommodating the breaking changes may require updating your existing scripts.

Email us at cli@confluent.io with questions or comments.

Breaking Changes

confluent v2.0 includes several changes that break with the syntax or output structure of the previous major release. Scripts used to interact with confluent v1.x or ccloud v1.x may have to be updated to accommodate these changes.

Breaking changes for Confluent Cloud CLI and Confluent CLI

  1. iam role has moved under the iam rbac group. So, iam role is now iam rbac role.
  2. rolebinding has been renamed to role-binding and has been moved under the iam rbac group. So, iam rolebinding is now iam rbac role-binding.
  3. The config context group is now just context. Additionally, commands within this group have been updated to conform to the client’s broader syntax pattern:
    • context update updates an existing context.
    • context describe describes an existing context. By default, this describes the current context and therefore replaces config context current.

Breaking changes for Confluent Cloud

  1. The ccloud client name is changed to confluent.
  2. The connector command group is changed to connect. For example, connector create is now connect create.
  3. The connector-catalog group is now connect plugin. For example, connector-catalog list is now connect plugin list.
  4. The ksql app create command now requires --api-key and --api-secret flags. Until now, these flags were optional.
  5. The value of resource ID properties, for example, for identifying users, service accounts, clusters, have been changed from integers to alphanumeric strings.
  6. Partition information has been removed from the output of kafka topic describe.
  7. In the kafka cluster describe command output, the property ApiEndpoint has been renamed KAPI, and is only visible if the --all flag is passed.
  8. In the kafka acl command group, the names of flags have been updated to match those of the Confluent REST Proxy.
  9. signup is now cloud-signup. Accessing this command does not require a preceding Confluent Cloud login.
  10. init has been replaced by context create.
  11. In api-key list, the --service-acount flag no longer erroneously accepts a user ID.
  12. The service-account commands have been moved under the iam group. So, service-account is now iam service-account.
  13. The user commands have been moved from the admin group to the iam group. So, the admin user group is now iam user.
  14. In iam user list and iam service-account list, the property resource_id has been renamed to id for consistency across the client.
  15. In the iam user group, invite is now invitation create. So, admin user invite is now iam user invitation create. This change made space for the new command iam user invitation list, which lists all of the pending invitations that have been created.

Breaking changes for Confluent CLI

  1. The secret command now requires authentication.
  2. In the iam acl command group, the names of flags have been updated to match those of the Confluent REST Proxy.

Environment variable name changes

Supported environment variable names have been updated as below:

CCLOUD_EMAILCONFLUENT_CLOUD_EMAIL

CCLOUD_PASSWORDCONFLUENT_CLOUD_PASSWORD

CONFLUENT_USERNAMECONFLUENT_PLATFORM_USERNAME

CONFLUENT_PASSWORDCONFLUENT_PLATFORM_PASSWORD

CONFLUENT_MDS_URLCONFLUENT_PLATFORM_MDS_URL

CONFLUENT_CA_CERT_PATHCONFLUENT_PLATFORM_CA_CERT_PATH

Migrate to Confluent CLI v2.x from Confluent Cloud CLI

ccloud v1.43, the last minor version of the client, will be released on November 9, 2021. Patch releases will continue to be released, if necessary, but no new functionality will be added.

From within any earlier ccloud version, ccloud update will update the client to this final release.

From ccloud v1.43, you can upgrade directly to the latest confluent v2.x release with the command:

ccloud update --major

ccloud will be sunset on May 9, 2022. At that point, ccloud will no longer be capable of authenticating into Confluent Cloud, and you will have to migrate to a confluent v2.x client in order to manage your Confluent Cloud deployment from the terminal.

Migrate to Confluent CLI v2.x from Confluent CLI v1.x

confluent v1.x is only capable of Confluent Platform management. Note that Confluent Platform comes bundled with a compatible version of confluent.

Confluent Platform v7.1 will be the first version that is interoperable with the confluent v2.x client. Therefore, if you are using a Confluent Platform version prior to v7.1, you should not migrate to confluent v2.x. See the interoperability guide for complete details on Confluent Platform-to-confluent compatibility.

Although it is unlikely to be necessary due to interoperability concerns, you can also upgrade to confluent v2.x directly from confluent v1.43 with the command:

confluent update --major

Directly install Confluent CLI v2.x

See the Installation Guide on how to download and install confluent v2.x directly.

Run multiple CLIs in parallel

It’s possible to run multiple confluent versions in parallel. For example, you can manage a legacy Confluent Platform deployment with a confluent v1.x client, as well as manage a Confluent Cloud deployment with a confluent v2.x client, from the same machine’s terminal.