Consul K8s CLI Reference

Consul K8s CLI is a tool for quickly installing and interacting with Consul on Kubernetes. The Consul K8s CLI allows you to manage the lifecycle of Consul without requiring the usage of Helm, Consul CLI, and kubectl. The Consul K8s CLI offers a Kubernetes native experience for managing Consul.

Note: For guidance on how to install the Consul K8s CLI, visit the Installing the Consul K8s CLI documentation.

This topic describes the subcommands and available options for using Consul K8s CLI.

Usage

Consul K8s CLI uses the following syntax:

  1. $ consul-k8s <SUBCOMMAND> <OPTIONS>
  1. $ consul-k8s <SUBCOMMAND> <OPTIONS>

Subcommands

You can use the following subcommands with consul-k8s.

install

The install command installs Consul on Kubernetes.

  1. $ consul-k8s install <OPTIONS>
  1. $ consul-k8s install <OPTIONS>

The following options are available.

FlagDescriptionDefaultRequired
-auto-approve                                    Boolean value that enables you to skip the installation confirmation prompt.falseOptional
-dry-runBoolean value that validates the installation and returns a summary.falseOptional
-config-fileString value that specifies the path to a file containing custom installation configurations, e.g., Consul Helm chart values file.
You can use the -config-file flag multiple times to specify multiple files.		noneOptional
-namespaceString value that specifies the namespace of the Consul installation.consulOptional
-presetString value that installs Consul based on a preset configuration. You can specify the following values:
demo: Installs a single replica server with sidecar injection enabled; useful for testing service mesh functionality.
secure: Installs a single replica server with sidecar injection, ACLs, and TLS enabled; useful for testing service mesh functionality.		Configuration of the Consul Helm chart.Optional
-setString value that enables you to set a customizable value. This flag is comparable to the helm install —set flag.
You can use the -set flag multiple times to set multiple values.
Consul Helm chart values are supported.		noneOptional
-set-fileString value that specifies the name of an arbitrary config file. This flag is comparable to the helm install —set-file
flag. The contents of the file will be used to set a customizable value. You can use the -set-file flag multiple times to specify multiple files.
Consul Helm chart values are supported.		noneOptional
-set-stringString value that enables you to set a customizable string value. This flag is comparable to the helm install —set-string
flag. You can use the -set-string flag multiple times to specify multiple strings.
Consul Helm chart values are supported.		noneOptional
-timeoutSpecifies how long to wait for the installation process to complete before timing out. The value is specified with an integer and string value indicating a unit of time.
The following units are supported:
ms (milliseconds)
s (seconds)
m (minutes)
In the following example, installation will timeout after one minute:
consul-k8s install -timeout 1m		10mOptional
-waitBoolean value that determines if Consul should wait for resources in the installation to be ready before exiting the command.trueOptional
-verbose, -vBoolean value that specifies whether to output verbose logs from the install command with the status of resources being installed.falseOptional
—helpPrints usage information for this option.noneOptional

See Global Options for additional commands that you can use when installing Consul on Kubernetes.

Example Commands

The following example command installs Consul according in the myNS namespace according to the secure preset.

  1. $ consul-k8s install -preset=secure -namespace=myNS
  1. $ consul-k8s install -preset=secure -namespace=myNS

The following example commands install Consul on Kubernetes using custom values, files, or strings that are set via flags. The underlying Consul-on-Kubernetes Helm chart uses the flags to customize the installation. The flags are comparable to the helm install flags.

  1.  $ consul-k8s install -set key=value
  1.  $ consul-k8s install -set key=value
  1.  $ consul-k8s install -set key1=value1 -set key2=value2
  1.  $ consul-k8s install -set key1=value1 -set key2=value2
  1.  $ consul-k8s install -set-file config1=value1.conf
  1.  $ consul-k8s install -set-file config1=value1.conf
  1.  $ consul-k8s install -set-file config1=value1.conf -set-file config2=value2.conf
  1.  $ consul-k8s install -set-file config1=value1.conf -set-file config2=value2.conf
  1.  $ consul-k8s install -set-string key=value-bool
  1.  $ consul-k8s install -set-string key=value-bool

uninstall

The uninstall command removes Consul from Kubernetes.

  1. $ consul-k8s uninstall <OPTIONS>
  1. $ consul-k8s uninstall <OPTIONS>

The following options are available.

FlagDescriptionDefaultRequired
-auto-approve                                    Boolean value that enables you to skip the removal confirmation prompt.falseOptional
-nameString value for the name of the installation to remove.noneOptional
-namespaceString value that specifies the namespace of the Consul installation to remove.consulOptional
-timeoutSpecifies how long to wait for the removal process to complete before timing out. The value is specified with an integer and string value indicating a unit of time.
The following units are supported:
ms (milliseconds)
s (seconds)
m (minutes)
h (hours)
In the following example, removal will timeout after one minute:
consul-k8s uninstall -timeout 1m		10mOptional
-wipe-dataBoolean value that deletes PVCs and secrets associated with the Consul installation during installation.
Data will be removed without a verification prompt if the -auto-approve flag is set to true.		false
Instructions for removing data will be printed to the console.		Optional
—helpPrints usage information for this option.noneOptional

See Global Options for additional commands that you can use when uninstalling Consul from Kubernetes.

Example Command

The following example command immediately uninstalls Consul from the my-ns namespace with the name my-consul and removes PVCs and secrets associated with the installation without asking for verification:

  1. $ consul-k8s uninstall -namespace=my-ns -name=my-consul -wipe-data=true -auto-approve=true
  1. $ consul-k8s uninstall -namespace=my-ns -name=my-consul -wipe-data=true -auto-approve=true

status

The status command provides an overall status summary of the Consul on Kubernetes installation. It also provides the config that was used to deploy Consul K8s and provides a quick glance at the health of both Consul servers and clients. This command does not take in any flags.

  1. $ consul-k8s status
  1. $ consul-k8s status

Example Command

  1. $ consul-k8s status
  3. ==> Consul-K8s Status Summary
  4.    NAME  | NAMESPACE |  STATUS  | CHARTVERSION | APPVERSION | REVISION |      LAST UPDATED
  5. ---------+-----------+----------+--------------+------------+----------+--------------------------
  6.   consul | consul    | deployed | 0.41.1       | 1.11.4     |        1 | 2022/03/10 07:48:58 MST
  8. ==> Config:
  9.     connectInject:
  10.       enabled: true
  11.       metrics:
  12.         defaultEnableMerging: true
  13.         defaultEnabled: true
  14.         enableGatewayMetrics: true
  15.     controller:
  16.       enabled: true
  17.     global:
  18.       metrics:
  19.         enableAgentMetrics: true
  20.         enabled: true
  21.       name: consul
  22.     prometheus:
  23.       enabled: true
  24.     server:
  25.       replicas: 1
  26.     ui:
  27.       enabled: true
  28.       service:
  29.         enabled: true
  31.  ✓ Consul servers healthy (1/1)
  32.  ✓ Consul clients healthy (3/3)
  1. $ consul-k8s status
  3. ==> Consul-K8s Status Summary
  4.    NAME  | NAMESPACE |  STATUS  | CHARTVERSION | APPVERSION | REVISION |      LAST UPDATED
  5. ---------+-----------+----------+--------------+------------+----------+--------------------------
  6.   consul | consul    | deployed | 0.41.1       | 1.11.4     |        1 | 2022/03/10 07:48:58 MST
  8. ==> Config:
  9.     connectInject:
  10.       enabled: true
  11.       metrics:
  12.         defaultEnableMerging: true
  13.         defaultEnabled: true
  14.         enableGatewayMetrics: true
  15.     controller:
  16.       enabled: true
  17.     global:
  18.       metrics:
  19.         enableAgentMetrics: true
  20.         enabled: true
  21.       name: consul
  22.     prometheus:
  23.       enabled: true
  24.     server:
  25.       replicas: 1
  26.     ui:
  27.       enabled: true
  28.       service:
  29.         enabled: true
  31.  ✓ Consul servers healthy (1/1)
  32.  ✓ Consul clients healthy (3/3)

upgrade

The consul-k8s upgrade subcommand is currently in beta: This subcommand is not recommended for production environments.

The upgrade command upgrades the Consul on Kubernetes components to the current version of the consul-k8s cli. Prior to running consul-k8s upgrade, the consul-k8s CLI should first be upgraded to the latest version as described Upgrade the Consul K8s CLI

  1. $ consul-k8s upgrade
  1. $ consul-k8s upgrade

The following options are available.

FlagDescriptionDefaultRequired
-auto-approve                                    Boolean value that enables you to skip the upgrade confirmation prompt.falseOptional
-dry-runBoolean value that allows you to run pre-upgrade checks and returns a summary of the upgrade.falseOptional
-config-fileString value that specifies the path to a file containing custom upgrade configurations, e.g., Consul Helm chart values file.
You can use the -config-file flag multiple times to specify multiple files.		noneOptional
-namespaceString value that specifies the namespace of the Consul installation.consulOptional
-presetString value that upgrades Consul based on a preset configuration.Configuration of the Consul Helm chart.Optional
-setString value that enables you to set a customizable value. This flag is comparable to the helm upgrade —set flag.
You can use the -set flag multiple times to set multiple values.
Consul Helm chart values are supported.		noneOptional
-set-fileString value that specifies the name of an arbitrary config file. This flag is comparable to the helm upgrade —set-file
flag. The contents of the file will be used to set a customizable value. You can use the -set-file flag multiple times to specify multiple files.
Consul Helm chart values are supported.		noneOptional
-set-stringString value that enables you to set a customizable string value. This flag is comparable to the helm upgrade —set-string
flag. You can use the -set-string flag multiple times to specify multiple strings.
Consul Helm chart values are supported.		noneOptional
-timeoutSpecifies how long to wait for the upgrade process to complete before timing out. The value is specified with an integer and string value indicating a unit of time.
The following units are supported:
ms (milliseconds)
s (seconds)
m (minutes)
In the following example, the upgrade will timeout after one minute:
consul-k8s upgrade -timeout 1m		10mOptional
-waitBoolean value that determines if Consul should wait for resources in the upgrade to be ready before exiting the command.trueOptional
-verbose, -vBoolean value that specifies whether to output verbose logs from the upgrade command with the status of resources being upgraded.falseOptional
—helpPrints usage information for this option.noneOptional

See Global Options for additional commands that you can use when installing Consul on Kubernetes.

version

The version command prints the Consul on Kubernetes version. This command does not take any options.

  1. $ consul-k8s version
  1. $ consul-k8s version

You can also print the version with the --version flag.

  1. $ consul-k8s --version
  1. $ consul-k8s --version

Global Options

The following global options are available.

FlagDescriptionDefaultRequired
-context                  String value that sets the Kubernetes context to use for Consul K8s CLI operations.noneOptional
-kubeconfig
Alias: -c		String value that specifies the path to the kubeconfig file.
noneOptional