This topic describes how to install and use the Confluent CLI.
Install Confluent CLI
Download the Confluent CLI and install the latest binary file based on your operating system.
Set the PATH environment variable to the directory in which the downloaded binary file is stored.
export PATH=<path-to-cli>:$PATH(Optional) If the default directory for CLI logs and data does not have enough storage space, you can set the CONFLUENT_CURRENT environment variable to another directory that you want to use.
export CONFLUENT_CURRENT=<path-to-confluent-local-data>In the Confluent CLI, run the following command:
confluentCheck whether information similar to the following one is returned:
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 on to Confluent CLI
Log on to Confluent Platform Metadata Service (MDS) using the username and password of your Lightweight Directory Access Protocol (LDAP) user. MDS uses HTTPS for encrypted transmission.
Username and password: You can obtain and manage the username and password of your LDAP user on the Users page in the ApsaraMQ for Confluent console. If you want to use a new user, grant the required permissions to it first. For more information, see Manage users and grant permissions to them.
Endpoint used to access MDS: You can obtain the endpoint used to access MDS on the Access Links and Ports page in the ApsaraMQ for Confluent console. In the following example, the public endpoint is used.
Certificate: You can download the certificate in the Certificate section of the Instance Details page in the ApsaraMQ for Confluent console.
In the Confluent CLI, run the following command to log on 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-passwordIf information similar to the following one is displayed, you are logged on to MDS.
[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 using Confluent CLI
When you run commands in the Confluent CLI, cluster IDs are required. The following sample code provides examples on how to query cluster IDs. Replace the url parameter with the corresponding service endpoint obtained from the Access Links and Ports page in the ApsaraMQ for Confluent console. For example, the public endpoint of the ksqlDB service is in the https://pub-ksqldb-xxxxxxxxxxx.csp.aliyuncs.com:443 format.
# View the information about the Kafka cluster.
confluent cluster describe --url <mds-url>
# View the information about the Schema Registry cluster.
confluent cluster describe --url <schema-registry-url>
# View the information about the ksqlDB cluster.
confluent cluster describe --url <ksqldb-url>Manage RBAC permissions using Confluent CLI
ApsaraMQ for Confluent provides predefined role-based access control (RBAC) roles. You can manage permissions based on them. For more information, see Use Predefined RBAC Roles in Confluent Platform. Before you use the Confluent CLI to manage permissions, you must log on to MDS.
This section describes common commands for managing RBAC permissions in the Confluent CLI. For more information, see Examples of RBAC authorization using Confluent CLI.
View the list of IAM roles
In ApsaraMQ for Confluent, Identity and Access Management (IAM) roles are used to define the access permissions of different users and services to resources. In most cases, the permissions are implemented based on RBAC. Users or services obtain specific permission sets by assuming the assigned roles.
Run the following command to view the list of IAM roles:
confluent iam rbac role listView the details of an IAM role
Run the following command to view the details of an IAM role:
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).Bind an IAM role to a user
Run the following command to bind an IAM role to a 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).Sample code:
# Bind the DeveloperRead role of the Schema Registry cluster to the sr-read user.
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>
# Bind the SystemAdmin role of the Schema Registry cluster to the sr-admin user.
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 users bound to an IAM role
Run the following command to view users bound to an IAM role:
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).Sample code:
# View users bound to the DeveloperRead role of the Schema Registry cluster.
confluent iam rbac role-binding list --role DeveloperRead --kafka-cluster <kafka-cluster-id> --schema-registry-cluster <schema-registry-cluster-id>
# View users bound to the SystemAdmin role of the Schema Registry cluster.
confluent iam rbac role-binding list --role SystemAdmin --kafka-cluster <kafka-cluster-id> --schema-registry-cluster <schema-registry-cluster-id>Remove an IAM role from a user
Run the following command to remove an IAM role from a user:
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).Sample code:
# Remove the DeveloperRead role of the Schema Registry cluster from the sr-read user.
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>
# Remove the SystemAdmin role of the Schema Registry cluster from the sr-admin user.
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 using Confluent CLI
This section describes common commands for managing access control lists (ACLs) using the Confluent CLI. For more information, see confluent iam acl.
Limit
You can create up to 1,000 ACLs for a cluster.
Creates 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).ACLs created for IAM roles in ApsaraMQ for Confluent support rules on IPv6 addresses, but do not support rules on CIDR blocks or subnets.
By default, access from addresses outside the created ACLs is denied. You can also use the --deny flag to deny access from specific addresses. The --deny flag takes precedence over the --allow flag.
You can use ACLs to manage permissions on groups and users. You can use the asterisk (*) wildcard character to grant permissions to all principals.
You can use the --prefix flag to specify a prefix and manage permissions on resources whose names contain the prefix. For example, if you include --topic abc- and --prefix in the command when you create an ACL, the ACL applies to all topics whose names start with abc-.
For example, if you want to create an ACL that allows the user Bob whose IP address is 198.51.xx.xx to read data from the test-topic topic in 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>Run the following commands to allow all users except BadBob to read data from the test-topic topic in a specific Kafka cluster:
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).The following sample code provides an example of how to view all ACLs of a specific Kafka cluster:
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).Sample code:
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 more information about Confluent CLI commands, see Confluent CLI Command Reference.