Migrate to Confluent CLI v2

Important

We’ve become aware of a bug that prevents the CLI client confluent from functioning nominally on Windows machines in confluent v2.0.0, confluent v2.1.0, and confluent v2.1.1. A fix has been released as confluent v2.2.0.

If you are currently using confluent v2.0.0, confluent v2.1.0. or confluent v2.1.1 on a Windows machine, you will have to remove the existing client and perform a fresh install of confluent v2.2.0+. (The in-client update command will not update to confluent v2.2.0+ on Windows machines.) The terminal command curl -sL https://cnfl.io/cli | sh -s -- -b $(dirname $(which confluent)) will perform a clean install by overwriting the existing client, in place, with the latest release. See the Installation Guide for additional installation options.

If you are currently using the deprecated ccloud v1.x client, the command ccloud update --major will result in an update to the most recent version of confluent. Prior to performing this major update, please read the guide below, however.

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, allows you to manage both Confluent Cloud and Confluent Platform from the same CLI client.

ccloud will be sunset on September 6, 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 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 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 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. SSO refresh tokens now expire after 4 hours.
  3. The connector command group is changed to connect. For example, connector create is now connect create.
  4. The connector-catalog group is now connect plugin. For example, connector-catalog list is now connect plugin list.
  5. The ksql app create command now requires --api-key and --api-secret flags. Until now, these flags were optional.
  6. The value of resource ID properties, for example, for identifying users, service accounts, clusters, have been changed from integers to alphanumeric strings.
  7. Partition information has been removed from the output of kafka topic describe.
  8. In the kafka cluster describe command output, the property ApiEndpoint has been renamed KAPI, and is only visible if the --all flag is passed.
  9. In the kafka acl command group, the following parameter names in the outputs have been updated to match those of the Confluent REST Proxy.
    • ServiceAccountId → Principal
    • Resource → ResourceType
    • Name → ResourceName
    • Type → PatternType
  10. signup is now cloud-signup. Accessing this command does not require a preceding Confluent Cloud login.
  11. init has been replaced by context create.
  12. In api-key list, the --service-acount flag no longer erroneously accepts a user ID.
  13. The service-account commands have been moved under the iam group. So, service-account is now iam service-account.
  14. The user commands have been moved from the admin group to the iam group. So, the admin user group is now iam user.
  15. In iam user list and iam service-account list, the property resource_id has been renamed to id for consistency across the client.
  16. 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 following parameter names in the outputs have been updated to match those of the Confluent REST Proxy:
    • Resource → ResourceType
    • Name → ResourceName
    • Type → PatternType

Environment variable name changes

Supported environment variable names have been updated as below:

  • CCLOUD_EMAIL → CONFLUENT_CLOUD_EMAIL
  • CCLOUD_PASSWORD → CONFLUENT_CLOUD_PASSWORD
  • CONFLUENT_USERNAME → CONFLUENT_PLATFORM_USERNAME
  • CONFLUENT_PASSWORD → CONFLUENT_PLATFORM_PASSWORD
  • CONFLUENT_MDS_URL → CONFLUENT_PLATFORM_MDS_URL
  • CONFLUENT_CA_CERT_PATH → CONFLUENT_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 September 6, 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

Confluent Platform 7.0 and lower versions are not fully interoperable with the recently released confluent v2 CLI client. confluent v2, however, is the most recent CLI client for managing Confluent Cloud.

Starting in v7.1, Confluent Platform will ship with a CLI version that is capable of managing both Confluent Platform and Confluent Cloud. If you want to manage both Confluent Platform and Confluent Cloud from the same machine before Confluent Platform v7.1 is available, set up and run confluent v1 and confluent v2 in parallel as described in this section.

For example, you can manage a Confluent Platform deployment with a confluent v1.x client and manage a Confluent Cloud deployment with a confluent v2.x client.

Setup

Set up a local environment for confluent v1

  1. If you have an existing confluent client, for example, one that was packaged with Confluent Platform, remove it to avoid confusion:

    rm $(which confluent)

  2. Create a directory for confluent v1 and its corresponding config file. Ensure that this directory is NOT part of your $PATH:

    mkdir ~/confluent-v1/

  3. Download a new instance of the confluent v1 binary to the confluent-v1 directory.

    In this example, we’re downloading confluent v1.43.1, which is compatible with Confluent Platform v7.0.

    See the full Confluent CLI to Confluent Platform interoperability table.

    We recommend using the latest Confluent CLI version that is compatible with your Confluent Platform version.

    For reference, full CLI installation instructions can be found Install Confluent CLI.

    curl -sL https://cnfl.io/cli | sh -s -- -b ~/confluent-v1 v1.43.1

  4. Create an alias for confluent v1.

    Consider adding this alias definition to your shell’s startup file (.bashrc, .zshrc, etc…), so it is sourced before each session. The alias will make the client easier to use from the terminal. It also ensures your confluent v1 configuration file is stored in the ~/confluent-v1 directory, and will not conflict with the configuration file for the confluent v2 client you’ll install shortly.

    alias confluent-v1="HOME=~/confluent-v1 ~/confluent-v1/confluent"

  5. Verify that a configuration file has been created in the ~/confluent-v1 directory:

    confluent-v1 version

    ls ~/confluent-v1/.confluent/config.json

  6. Disable update messages for this version:

    echo '{"disable_updates": true}' > ~/confluent-v1/.confluent/config.json
Set up confluent v2 globally.

  1. Download the latest version of confluent v2:

    curl -sL https://cnfl.io/cli | sh -s -- -b /usr/local/bin

  2. Add confluent v2 to your $PATH:

    export PATH="/usr/local/bin:$PATH"

  3. Optionally, if you had previously been using a now-deprecated ccloud client for Confluent Cloud management, you can remove it.

    rm $(which ccloud)

Run CLIs in parallel

To manage Confluent Platform with confluent v1:

confluent-v1 login --url <mds-url>

confluent-v1 [command]

For details, see Log into an RBAC-enabled Confluent Platform cluster.

To manage Confluent Cloud with confluent v2:

confluent login

confluent [command]

For details, see Connect to a Confluent Cloud cluster.