Consul Resource
Command: consul resource
Use the resource
command to apply, list, read, and delete resources when interacting with Consul's v2 catalog through the command line. For more information, refer to v2 catalog API.
The consul resource
command has usage limitations in Consul v1.17.0. The CLI does not accept partition, namespace, and peer arguments, but the v2 catalog outputs this information when you add the read
or list
subcommand. In addition, do not use the apply
and delete
commands with Consul on Kubernetes in this release. Use the kubectl
command to apply or delete resources instead. Refer to configure multi-port services for an example of the workflow to apply resources.
Usage
On Kubernetes deployments, you must use a kubectl exec
command to open a shell to the Consul server's container before you can run this Consul CLI command.
Subcommands
You can issue the following subcommands with the consul resource
command.
apply
consul resource apply
writes or updates a resource at a given file path.
The following table shows the required ACLs permission to run the apply
command:
ACL Required |
---|
operator:write |
Command Options
-f=<filepath>
- (Required) The path to the file that defines the Consul resource. When the file that defines the resource is in the current working directory, you may optionally omit this flag and pass the resource filename only.
Example usage
The following command applies a traffic permissions resource to Consul that restricts service-to-service communication to authorized services only.
delete
consul resource delete
removes a Consul resource at a given file path.
The following table shows the required ACL permissions to run the delete
command:
ACL Required |
---|
operator:write |
Command Options
-f=<filepath>
- (Required) The path to the file that defines the Consul resource. When the file that defines the resource is in the current working directory, you may optionally omit this flag and pass the resource filename only.
Example usage
The following command removes a traffic permissions resource from Consul that restricts service-to-service communication to authorized services only.
list
consul resource list
outputs information about resources according to the type of resource and the location where the resource is applied.
This command must be issued with a resource type. All resource definitions include a type
configuration block that contains a group
, groupVersion
, and kind
. By formatting the type
on the command line as group.groupVersion.kind
, you can return all resources with a matching type
in the configuration.
The following table shows the required ACL permissions to run the list
command:
ACL Required |
---|
operator:read |
Command Options
The following flags enable you to filter results.
-partition=<string>
- The partition where the resources apply.-namespace=<string>
- The namespace where the resources apply.-peer=<string>
- The clusters with established cluster peering connections where the resources apply.
Example usage
The following command lists resources that apply to services registered with the v2 catalog API, and includes a sample output for the api
and web
services registered in configure multi-port services:
read
consul resource read
outputs information about resources according to the type and name of the resource.
The following table shows the required ACL permissions to run the read
command:
ACL Required |
---|
operator:read |
Command Options
-partition=<string>
- The partition where the resource applies.-namespace=<string>
- The namespace where the resource applies.-peer=<string>
- The clusters with established cluster peering connections where the resource applies.-stale
- Permits any Consul server to respond to the request. This flag enables for lower latency and higher throughput, but may result in stale data. This option has no effect on non-read operations.
Example usage
In the following example, the output for reading the resource for the web
service includes information such as ports, virtual IPs, and workload identity.