rpk acl
Manage ACLs and SASL users.
This command space creates, lists, and deletes ACLs, as well as creates SASL
users. The help text below is specific to ACLs. To learn about SASL users,
check the help text under the user
command.
When using SASL, ACLs allow or deny you access to certain requests. The
create
, delete
, and list
commands help you manage your ACLs.
An ACL is made up of five components:
-
a principal (the user)
-
a host the principal is allowed or denied requests from
-
what resource to access (topic name, group ID, etc)
-
the operation (read, write, etc)
-
the permission, whether to allow or deny the above
ACL commands work on a multiplicative basis. If creating, specifying two principals and two permissions creates four ACLs: both permissions for the first principal, as well as both permissions for the second principal. Adding two resources further doubles the ACLs created.
It is recommended to be as specific as possible when granting ACLs. Granting more ACLs than necessary per principal may inadvertently allow clients to do things they should not, such as deleting topics or joining the wrong consumer group.
Principals
All ACLs require a principal. A principal is composed of two parts: the type
and the name. Within Redpanda, only one type is supported, User
. The reason
for the prefix is that a potential future authorizer may add support for
authorizing by Group or anything else.
When you create a user, you need to add ACLs for it before it can be used. You
can create/delete/list ACLs for that user with either User:bar
or bar
in the --allow-principal
and --deny-principal
flags. This command will add the
User:
prefix for you if it is missing. The wildcard matches any user.
Creating an ACL with user
grants or denies the permission for all users.
To set multiple principals in a single comma-separated string, you must enclose the string with quotes. Otherwise, For example, use double quotes:
Alternatively, use single quotes:
|
Hosts
Hosts can be seen as an extension of the principal, and effectively gate where
the principal can connect from. When creating ACLs, unless otherwise specified,
the default host is the wildcard *
which allows or denies the principal from
all hosts (where allow & deny are based on whether --allow-principal
or
--deny-principal
is used). If specifying hosts, you must pair the --allow-host
flag with the --allow-principal
flag, and the --deny-host
flag with the
--deny-principal
flag.
Resources
A resource is what an ACL allows or denies access to. There are four resources within Redpanda: topics, groups, the cluster itself, and transactional IDs. Names for each of these resources can be specified with their respective flags.
Resources combine with the operation that is allowed or denied on that resource. The next section describes which operations are required for which requests, and further fleshes out the concept of a resource.
By default, resources are specified on an exact name match (a literal
match).
The --resource-pattern-type flag can be used to specify that a resource name is
prefixed
, meaning to allow anything with the given prefix. A literal name of
foo
will match only the topic foo
, while the prefixed name of foo-
will
match both foo-bar
and foo-baz
. The special wildcard resource name
matches any name of the given resource type (--topic
matches all topics).
Operations
Pairing with resources, operations are the actions that are allowed or denied. Redpanda has the following operations:
Operation |
Description |
|
Allows all operations below. |
|
Allows reading a given resource. |
|
Allows writing to a given resource. |
|
Allows creating a given resource. |
|
Allows deleting a given resource. |
|
Allows altering non-configurations. |
|
Allows querying non-configurations. |
|
Allows describing configurations. |
|
Allows altering configurations. |
You can run rpk acl --help-operations
to see which operations are required for which
requests. In flag form to set up a general producing/consuming client, you can
invoke rpk acl create
three times with the following (including your
--allow-principal
):
`rpk acl create --operation write,read,describe --topic [topics] `
rpk acl create --operation describe,read --group [group.id]
rpk acl create --operation describe,write --transactional-id [transactional.id]
Permissions
A client can be allowed access or denied access. By default, all permissions are denied. You only need to specifically deny a permission if you allow a wide set of permissions and then want to deny a specific permission in that set. You could allow all operations, and then specifically deny writing to topics.
Management
Creating ACLs works on a specific ACL basis, but listing and deleting ACLs works on filters. Filters allow matching many ACLs to be printed listed and deleted at once. Because this can be risky for deleting, the delete command prompts for confirmation by default. More details and examples for creating, listing, and deleting can be seen in each of the commands.
Using SASL requires setting enable_sasl: true
in the redpanda section of your
redpanda.yaml
. User management is a separate, simpler concept that is
described in the user command.
Matching Rules
The matching rules are only applied to commands that have filters, such as rpk acl delete
and rpk acl list
.
Not specifying flags matches everything. If no resources are
specified, all resources are matched. If no operations are specified, all
operations are matched. You can also opt in to matching everything with any: --operation
matches any operation.
The --resource-pattern-type
, defaulting to any
, configures how to filter
resource names:
Matching rule | Description |
---|---|
|
returns exact name matches of either prefixed or literal pattern type. |
|
returns wildcard matches, prefix patterns that match your input, and literal matches. |
|
returns prefix patterns that match your input (prefix |
|
returns exact name matches. |
Flags available for every command
Every rpk acl
can have these flags attached to them:
Flag | Type | Description |
---|---|---|
--brokers |
strings |
Comma-separated list of broker <ip>:<port> pairs (for example,\{" "} ` {" "} --brokers '192.168.78.34:9092,192.168.78.35:9092,192.179.23.54:9092'{" "} ` ). Alternatively, you may set the ` REDPANDA_BROKERS ` environment variable with the comma-separated list of broker addresses. |
--config |
string |
Redpanda config file, if not set the file will be searched for in the default locations. |
--password |
string |
SASL password to be used for authentication. |
--sasl-mechanism |
string |
The authentication mechanism to use.
Supported values:\{" "} |
--tls-cert |
string |
The certificate to be used for TLS authentication with the broker. |
--tls-enabled |
- |
Enable TLS for the Kafka API (not necessary if specifying custom certs). |
--tls-key |
string |
The certificate key to be used for TLS authentication with the broker. |
--tls-truststore |
string |
The truststore to be used for TLS communication with the broker. |
--user |
string |
SASL user to be used for authentication. |
-v, --verbose |
- |
Enable verbose logging (default |
Flags
Every rpk acl
can have these flags attached to them:
Value | Type | Description |
---|---|---|
--admin-api-tls-cert |
string |
The certificate to be used for TLS authentication with the Admin API. |
--admin-api-tls-enabled |
- |
Enable TLS for the Admin API (not necessary if specifying custom certs). |
--admin-api-tls-key |
string |
The certificate key to be used for TLS authentication with the Admin API. |
--admin-api-tls-truststore |
string |
The truststore to be used for TLS communication with the Admin API. |
--brokers |
strings |
Comma-separated list of broker <ip>:<port> pairs
(for example,\{" "}
` --brokers '192.168.78.34:9092,192.168.78.35:9092,192.179.23.54:9092' `
). Alternatively, you may set the |
--config |
string |
Redpanda config file, if not set the file will be searched for in the default locations. |
-h, --help |
- |
Help for acl. |
--help-operations |
- |
Print more help about ACL operations. |
--password |
string |
SASL password to be used for authentication. |
--sasl-mechanism |
string |
The authentication mechanism to use.
Supported values:\{" "} |
--tls-cert |
string |
The certificate to be used for TLS authentication with the broker. |
--tls-enabled |
- |
Enable TLS for the Kafka API (not necessary if specifying custom certs). |
--tls-key |
string |
The certificate key to be used for TLS authentication with the broker. |
--tls-truststore |
string |
The truststore to be used for TLS communication with the broker. |
--user |
string |
SASL user to be used for authentication. |
-v, --verbose |
- |
Enable verbose logging (default |