Install and use the Confluent CLI-ApsaraMQ for Kafka(Kafka)-阿里云帮助中心

Install and use the command-line interface (CLI) for Message Queue for Confluent to manage clusters, permissions, and resources from a terminal.

Install the Confluent CLI

Download the Confluent CLI and install the latest binary file for your operating system.
Add the directory of the CLI binary file to your PATH environment variable.
```
export PATH=<path-to-cli>:$PATH
```
(Optional) If the default directory where the CLI stores logs and data has insufficient space, you can set the CONFLUENT_CURRENT environment variable to a different directory.
```
export CONFLUENT_CURRENT=<path-to-confluent-local-data>
```
Run the following command in your terminal:
```
confluent
```

The command returns the following output.

Manage your Confluent Platform.

Usage:
  confluent [command]

Available Commands:
  audit-log            Manage audit log configuration.
  cloud-signup         Sign up for Confluent Cloud.
  cluster              Retrieve metadata about Confluent Platform clusters.
  completion           Print shell completion code.
  configuration        Configure the Confluent CLI.
  connect              Manage Kafka Connect.
  context              Manage CLI configuration contexts.
  flink                Manage Apache Flink.
  help                 Help about any command
  iam                  Manage RBAC, ACL and IAM permissions.
  kafka                Manage Apache Kafka.
  ksql                 Manage ksqlDB.
  local                Manage a local Confluent Platform development environment.
  login                Log in to Confluent Cloud or Confluent Platform.
  logout               Log out of Confluent Platform.
  plugin               Manage Confluent plugins.
  prompt               Add Confluent CLI context to your terminal prompt.
  schema-registry      Manage Schema Registry.
  secret               Manage secrets for Confluent Platform.
  shell                Start an interactive shell.
  update               Update the Confluent CLI.
  version              Show version of the Confluent CLI.

Flags:
      --version         Show version of the Confluent CLI.
  -h, --help            Show help for this command.
      --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
  -v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

Use "confluent [command] --help" for more information about a command.

Log in to the Confluent CLI

To use the Confluent CLI, you must log in to MDS, which authenticates with a username and password over HTTPS.
- Username and password: Manage your username and password on the Users page in the Message Queue for Confluent console. If you use a new user, you must also grant the required permissions. For more information, see User management and authorization.
- MDS address: Obtain the MDS address from the Access Links and Ports page in the Message Queue for Confluent console. This example uses a public endpoint.
- Certificate: Download the certificate from the Certificate section on the Instance Details page in the Message Queue for Confluent console.

Run the following command in your terminal to log in to MDS.

confluent login --url https://pub-kafka-xxxxxxxxx.csp.aliyuncs.com:443 --certificate-authority-path  xxxxx.pem
Enter your Confluent credentials:
Username: your-username
Password: your-password

The following output indicates a successful login.

[root@iZbp13z******** cli]# confluent login --url https://pub-kafka-xxxxxxxxx.csp.aliyuncs.com:443 --certificate-authority-path  xxxxx.pem
Enter your Confluent credentials:
Username: root
Password: ********
[root@iZbp13z******** cli]#

View cluster information

The Confluent CLI requires the ID of each cluster. Run the following commands to query cluster IDs. Replace the url parameter with the endpoint for each service, which you can obtain from the Access Links and Ports page in the Message Queue for Confluent console. For example, the public endpoint for the ksqlDB service is https://pub-ksqldb-xxxxxxxxxxx.csp.aliyuncs.com:443.

# View Kafka cluster information
confluent cluster describe --url <mds-url>

# View Schema Registry cluster information
confluent cluster describe --url <schema-registry-url>

# View ksqlDB cluster information
confluent cluster describe --url <ksqldb-url>

Manage RBAC permissions

Note

Message Queue for Confluent provides predefined roles for managing permissions. For more information about these roles, see Introduction to predefined roles. Before managing permissions with the Confluent CLI, you must log in to MDS.

The following commands cover the main operations for managing Role-Based Access Control (RBAC) permissions. For more operations, see Examples of RBAC authorization using Confluent CLI.

View IAM roles

In Message Queue for Confluent, Identity and Access Management (IAM) roles define access permissions for users and services. Assigning a role to a principal grants a specific set of permissions through RBAC.

Run the following command to view the resource types and operations that each role can perform.

confluent iam rbac role list

View IAM role details

Run the following command to view the resources and operations that a specific role allows.

confluent iam rbac role describe <name> [flags]

Flags

    --client-cert-path string   Path to client cert to be verified by MDS. Include for mTLS authentication.
    --client-key-path string    Path to client private key, include for mTLS authentication.
    --context string            CLI context name.
-o, --output string             Specify the output format as "human", "json", or "yaml". (default "human")

Global flags

 -h, --help            Show help for this command.
     --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
 -v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

Create an IAM role binding

Run the following command to grant a role on a cluster to a specific user.

confluent iam rbac role-binding create [flags]

Flags

      --role string                      REQUIRED: Role name of the new role binding.
      --principal string                 REQUIRED: Principal type and identifier using "Prefix:ID" format.
      --kafka-cluster string             Kafka cluster ID for the role binding.
      --schema-registry-cluster string   Schema Registry cluster ID for the role binding.
      --ksql-cluster string              ksqlDB cluster ID for the role binding.
      --connect-cluster string           Kafka Connect cluster ID for the role binding.
      --cmf string                       Confluent Managed Flink (CMF) ID, which specifies the CMF scope.
      --flink-environment string         Flink environment ID, which specifies the Flink environment scope.
      --cluster-name string              Cluster name to uniquely identify the cluster for role binding listings.
      --context string                   CLI context name.
      --resource string                  Resource type and identifier using "Prefix:ID" format.
      --prefix                           Whether the provided resource name is treated as a prefix pattern.
      --client-cert-path string          Path to client cert to be verified by MDS. Include for mTLS authentication.
      --client-key-path string           Path to client private key, include for mTLS authentication.
  -o, --output string                    Specify the output format as "human", "json", or "yaml". (default "human")

Global flags

  -h, --help            Show help for this command.
      --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
  -v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

Examples:

# Grant the user sr-read the DeveloperRead role for the Schema Registry on a Kafka cluster.
confluent iam rbac role-binding create --principal User:sr-read --role DeveloperRead --resource Subject:* --kafka-cluster <kafka-cluster-id> --schema-registry-cluster <schema-registry-cluster-id>

# Grant the user sr-admin the SystemAdmin role for the Schema Registry on a Kafka cluster.
confluent iam rbac role-binding create --principal User:sr-admin --role SystemAdmin  --kafka-cluster <kafka-cluster-id> --schema-registry-cluster <schema-registry-cluster-id>

View IAM role bindings

Run the following command to query role bindings for a specific user, role, or scope.

confluent iam rbac role-binding list [flags]

Flags

      --principal string                 Principal ID, which limits role bindings to this principal. If unspecified, list all principals and role bindings.
      --current-user                     List role bindings assigned to the current user.
      --role string                      Predefined role assigned to "--principal". If "--principal" is unspecified, list all principals assigned the role.
      --kafka-cluster string             Kafka cluster ID, which specifies the Kafka cluster scope.
      --schema-registry-cluster string   Schema Registry cluster ID, which specifies the Schema Registry cluster scope.
      --ksql-cluster string              ksqlDB cluster ID, which specifies the ksqlDB cluster scope.
      --connect-cluster string           Kafka Connect cluster ID, which specifies the Connect cluster scope.
      --cmf string                       Confluent Managed Flink (CMF) ID, which specifies the CMF scope.
      --flink-environment string         Flink environment ID, which specifies the Flink environment scope.
      --client-cert-path string          Path to client cert to be verified by MDS. Include for mTLS authentication.
      --client-key-path string           Path to client private key, include for mTLS authentication.
      --context string                   CLI context name.
      --cluster-name string              Cluster name, which specifies the cluster scope.
      --resource string                  Resource type and identifier using "Prefix:ID" format. If specified with "--role" and no principals, list all principals and role bindings.
      --inclusive                        List role bindings for specified scopes and nested scopes. Otherwise, list role bindings for the specified scopes. If scopes are unspecified, list only organization-scoped role bindings.
  -o, --output string                    Specify the output format as "human", "json", or "yaml". (default "human")

Global flags

  -h, --help            Show help for this command.
      --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
  -v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

Examples:

# View the role bindings for the DeveloperRead role on the Schema Registry.
confluent iam rbac role-binding list  --role DeveloperRead --kafka-cluster <kafka-cluster-id> --schema-registry-cluster <schema-registry-cluster-id>

# View the role bindings for the SystemAdmin role on the Schema Registry.
confluent iam rbac role-binding list  --role SystemAdmin --kafka-cluster <kafka-cluster-id> --schema-registry-cluster <schema-registry-cluster-id>

Delete an IAM role binding

Run the following command to delete a role binding.

confluent iam rbac role-binding delete [flags]

Flags

      --role string                      REQUIRED: Role name of the existing role binding.
      --principal string                 REQUIRED: Principal type and identifier using "Prefix:ID" format.
      --force                            Skip the deletion confirmation prompt.
      --kafka-cluster string             Kafka cluster ID for the role binding.
      --schema-registry-cluster string   Schema Registry cluster ID for the role binding.
      --ksql-cluster string              ksqlDB cluster ID for the role binding.
      --connect-cluster string           Kafka Connect cluster ID for the role binding.
      --cmf string                       Confluent Managed Flink (CMF) ID, which specifies the CMF scope.
      --flink-environment string         Flink environment ID, which specifies the Flink environment scope.
      --cluster-name string              Cluster name to uniquely identify the cluster for role binding listings.
      --context string                   CLI context name.
      --resource string                  Resource type and identifier using "Prefix:ID" format.
      --prefix                           Whether the provided resource name is treated as a prefix pattern.
      --client-cert-path string          Path to client cert to be verified by MDS. Include for mTLS authentication.
      --client-key-path string           Path to client private key, include for mTLS authentication.
  -o, --output string                    Specify the output format as "human", "json", or "yaml". (default "human")

Global flags

  -h, --help            Show help for this command.
      --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
  -v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

Examples:

# Delete the DeveloperRead role binding from the user sr-read for the Schema Registry.
confluent iam rbac role-binding delete --principal User:sr-read --role DeveloperRead --resource Subject:* --kafka-cluster <kafka-cluster-id> --schema-registry-cluster <schema-registry-cluster-id>

# Delete the SystemAdmin role binding from the user sr-admin for the Schema Registry.
confluent iam rbac role-binding delete --principal User:sr-admin --role SystemAdmin  --kafka-cluster <kafka-cluster-id> --schema-registry-cluster <schema-registry-cluster-id>

Manage ACLs

The following commands cover the main operations for managing an access control list (ACL). For more information, see confluent iam acl.

Limitations

A single cluster can have a maximum of 1,000 access control list (ACL) entries.

Create an ACL

Run the following command to create an ACL.

confluent iam acl create [flags]

Flags

--kafka-cluster string      REQUIRED: Kafka cluster ID for scope of ACL commands.
--principal string          REQUIRED: Principal for this operation, prefixed with "User:" or "Group:".
--operation string          REQUIRED: Set ACL Operation to: (all, alter, alter-configs, cluster-action, create, delete, describe, describe-configs, idempotent-write, read, write).
--host string               Set host for access. Only IP addresses are supported. (default "*")
--allow                     ACL permission to allow access.
--deny                      ACL permission to restrict access to resource.
--cluster-scope             Set the cluster resource. With this option the ACL grants access to the provided operations on the Kafka cluster itself.
--consumer-group string     Set the Consumer Group resource.
--transactional-id string   Set the TransactionalID resource.
--topic string              Set the topic resource. With this option the ACL grants the provided operations on the topics that start with that prefix, depending on whether the "--prefix" option was also passed.
--prefix                    Set to match all resource names prefixed with this value.
--client-cert-path string   Path to client cert to be verified by MDS. Include for mTLS authentication.
--client-key-path string    Path to client private key, include for mTLS authentication.
--context string            CLI context name.

Global flags

-h, --help            Show help for this command.
    --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
-v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

Important

confluent iam acl supports IPv6 addresses but not IP ranges or subnets.
By default, the system denies any access not explicitly authorized by an access control list (ACL). You can also use the --deny flag to explicitly deny access. The --deny flag has a higher priority than the --allow flag.
You can use an ACL to manage permissions for groups and users. You can use the wildcard character (*) to grant permissions to all principals.
When you create an ACL, you can use the --prefix flag to grant permissions on resources that match a specified prefix. For example, if you include --topic abc- and --prefix in your command, the permission applies to all topics whose names start with abc-.

For example, to create an ACL that allows the user Bob from IP address 198.51.xx.xx to perform read operations on the test-topic of a specific Kafka cluster, run the following command:

confluent iam acl create --allow --principal User:Bob --operation READ --host 198.51.xx.xx --topic test-topic  --kafka-cluster <kafka-cluster-id>

The following commands allow all users to read data from the test-topic in a specific Kafka cluster but deny access to the user BadBob.

confluent iam acl create --allow --principal User:'*' --operation READ --topic test-topic --kafka-cluster <kafka-cluster-id> 

confluent iam acl create --deny --principal User:BadBob --operation READ --topic test-topic  --kafka-cluster <kafka-cluster-id>

View ACLs

Run the following command to view ACLs.

confluent iam acl list [flags]

Flags

    --kafka-cluster string      REQUIRED: Kafka cluster ID for scope of ACL commands.
    --principal string          Principal for this operation, prefixed with "User:" or "Group:".
    --operation string          Set ACL Operation to: (all, alter, alter-configs, cluster-action, create, delete, describe, describe-configs, idempotent-write, read, write).
    --host string               Set host for access. Only IP addresses are supported. (default "*")
    --allow                     ACL permission to allow access.
    --deny                      ACL permission to restrict access to resource.
    --cluster-scope             Set the cluster resource. With this option the ACL grants access to the provided operations on the Kafka cluster itself.
    --consumer-group string     Set the Consumer Group resource.
    --transactional-id string   Set the TransactionalID resource.
    --topic string              Set the topic resource. With this option the ACL grants the provided operations on the topics that start with that prefix, depending on whether the "--prefix" option was also passed.
    --prefix                    Set to match all resource names prefixed with this value.
    --client-cert-path string   Path to client cert to be verified by MDS. Include for mTLS authentication.
    --client-key-path string    Path to client private key, include for mTLS authentication.
    --context string            CLI context name.
-o, --output string             Specify the output format as "human", "json", or "yaml". (default "human")

Global flags

-h, --help            Show help for this command.
    --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
-v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

For example, to list all ACLs for a specific cluster, run the following command:

confluent iam acl list --kafka-cluster <kafka-cluster-id>

Delete an ACL

Run the following command to delete an ACL.

confluent iam acl delete [flags]

Flags

--kafka-cluster string      REQUIRED: Kafka cluster ID for scope of ACL commands.
--principal string          REQUIRED: Principal for this operation, prefixed with "User:" or "Group:".
--operation string          REQUIRED: Set ACL Operation to: (all, alter, alter-configs, cluster-action, create, delete, describe, describe-configs, idempotent-write, read, write).
--host string               REQUIRED: Set host for access. Only IP addresses are supported. (default "*")
--allow                     ACL permission to allow access.
--deny                      ACL permission to restrict access to resource.
--cluster-scope             Set the cluster resource. With this option the ACL grants access to the provided operations on the Kafka cluster itself.
--consumer-group string     Set the Consumer Group resource.
--transactional-id string   Set the TransactionalID resource.
--topic string              Set the topic resource. With this option the ACL grants the provided operations on the topics that start with that prefix, depending on whether the "--prefix" option was also passed.
--prefix                    Set to match all resource names prefixed with this value.
--client-cert-path string   Path to client cert to be verified by MDS. Include for mTLS authentication.
--client-key-path string    Path to client private key, include for mTLS authentication.
--force                     Skip the deletion confirmation prompt.
--context string            CLI context name.

Global flags

-h, --help            Show help for this command.
    --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
-v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

Example:

confluent iam acl delete --allow --principal User:Bob --operation READ --host 198.51.xx.xx --topic test-topic  --kafka-cluster <kafka-cluster-id>

References

For the complete command manual, see the Confluent CLI Command Reference.