Blog HCP Consul on Azure goes GA, plus more Consul news from HashiConf EU Read more
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • Overview
      • Overview
      • What is a Service Mesh?
      • Overview
      • Chef, Puppet, etc.
      • Nagios
      • SkyDNS
      • SmartStack
      • Serf
      • Eureka
      • Istio
      • Envoy and Other Proxies
      • Custom Solutions
    • Overview
    • Manual Bootstrap
    • Consul Agent
    • Glossary
    • Required Ports
    • Bootstrapping a Datacenter
    • Cloud Auto-join
    • Server Performance
    • Kubernetes
  • API
  • Commands (CLI)
    • Register Services - Service Definitions
    • Find Services - DNS Interface
    • Monitor Services - Check Definitions
    • Overview
    • How Service Mesh Works
    • Configuration
      • Overview
      • Ingress Gateway
      • Mesh
      • Exported Services
      • Proxy Defaults
      • Service Defaults
      • Service Intentions
      • Service Resolver
      • Service Router
      • Service Splitter
      • Terminating Gateway
      • Overview
      • Envoy
      • Built-in Proxy
      • Proxy Integration
      • Managed (Deprecated)
      • Overview
      • Proxy Service Registration
      • Sidecar Service Registration
    • Service-to-service permissions - Intentions
    • Service-to-service permissions - Intentions (Legacy Mode)
    • Transparent Proxy
      • Overview
      • UI Visualization
      • Overview
      • Discovery Chain
    • Connectivity Tasks
    • Distributed Tracing
      • Overview
        • WAN Federation
        • Enabling Service-to-service Traffic Across Datacenters
        • Enabling Service-to-service Traffic Across Admin Partitions
      • Ingress Gateways
      • Terminating Gateways
      • What is Cluster Peering
      • Create and Manage Peering Connections
      • Cluster Peering on Kubernetes
    • Nomad
    • Kubernetes
      • Overview
      • Go Integration
      • Overview
      • Built-In CA
      • Vault
      • ACM Private CA
    • Develop and Debug
    • Security
    • Overview
    • Installation
    • Technical Specifications
    • Common Errors
    • Upgrades
    • Overview
    • Architecture
      • Installing Consul on Kubernetes
      • Installing Consul K8s CLI
        • Minikube
        • Kind
        • AKS (Azure)
        • EKS (AWS)
        • GKE (Google Cloud)
        • Red Hat OpenShift
        • Self Hosted Kubernetes
        • Consul Clients Outside Kubernetes
        • Consul Servers Outside Kubernetes
        • Single Consul Datacenter in Multiple Kubernetes Clusters
        • Consul Enterprise
        • Overview
        • Federation Between Kubernetes Clusters
        • Federation Between VMs and Kubernetes
        • Overview
        • Systems Integration
          • Overview
          • Bootstrap Token
          • Enterprise License
          • Gossip Encryption Key
          • Partition Token
          • Replication Token
          • Server TLS
          • Service Mesh Certificates
          • Snapshot Agent Config
          • Webhook Certificates
        • WAN Federation
      • Overview
      • Transparent Proxy
      • Ingress Gateways
      • Terminating Gateways
      • Ingress Controllers
      • Configuring a Connect CA Provider
      • Health Checks
        • Metrics
    • Service Sync
      • Overview
      • Upgrade An Existing Cluster to CRDs
    • Annotations and Labels
    • Consul DNS
      • Upgrading Consul on Kubernetes
      • Upgrading Consul K8s CLI
      • Uninstall
      • Certificate Rotation
      • Gossip Encryption Key Rotation
      • Configure TLS on an Existing Cluster
      • Common Error Messages
      • FAQ
    • Compatibility Matrix
    • Helm Chart Configuration
    • Consul K8s CLI Reference
    • Overview
    • Requirements
    • Task Resource Usage
      • Installation
      • Secure Configuration
      • Migrate Existing Tasks
      • Installation
      • Secure Configuration
      • ACL Controller
    • Architecture
    • Consul Enterprise
    • Configuration Reference
    • Overview
    • Register Lambda Functions
    • Invoke Lambda Functions
    • Overview
      • Installation
      • Requirements
      • Configure
      • Run Consul-Terraform-Sync
    • Architecture
      • Overview
      • Status
      • Tasks
      • Health
      • Overview
      • task
      • start
    • Configuration
    • Tasks
    • Terraform Modules
      • Overview
      • License
      • Terraform Cloud Driver
      • Overview
      • Terraform
      • Terraform Cloud
    • Compatibility
    • Consul KV
    • Sessions
    • Watches
    • Overview
      • General
      • CLI Reference
      • Configuration Reference
    • Configuration Entries
    • Telemetry
    • Sentinel
    • RPC
    • Overview
      • ACL System Overview
      • Tokens
      • Policies
      • Roles
      • Rules Reference
      • Legacy Mode
      • Token Migration
      • ACLs in Federated Datacenters
        • Overview
        • Kubernetes
        • JWT
        • OIDC
        • AWS IAM
    • Encryption
      • Overview
      • Core
      • Network Infrastructure Automation
    • Overview
    • Admin Partitions
    • Audit Logging
    • Automated Backups
    • Automated Upgrades
    • Enhanced Read Scalability
    • Single sign-on - OIDC
    • Redundancy Zones
    • Advanced Federation
    • Network Segments
    • Namespaces
    • NIA with TFE
    • Sentinel
      • Overview
      • FAQ
    • Overview
    • Improving Consul Resilience
    • Anti-Entropy
    • Consensus Protocol
    • Gossip Protocol
    • Jepsen Testing
    • Network Coordinates
    • Consul Integration Program
    • NIA Integration Program
    • Vault Integration
    • Proxy Integration
  • Consul Tools
    • Overview
    • Compatibility Promise
    • Specific Version Details
      • Overview
      • General Process
      • Upgrading to 1.2.4
      • Upgrading to 1.6.9
      • Upgrading to 1.8.13
      • Upgrading to 1.10.0
    • Common Error Messages
    • FAQ
    • Overview
      • v1.11.x
      • v1.10.x
      • v1.9.x
      • v0.3.x
      • v0.2.x
      • v0.1.x
      • v0.4.x
      • v0.3.x
      • v0.2.x
      • v0.6.x
      • v0.5.x
    • Overview
    • ACL
  • Guides
Type '/' to Search

»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:

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

»Subcommands

You can use the following subcommands with consul-k8s.

  • install
  • uninstall
  • status
  • upgrade BETA
  • version

»install

The install command installs Consul on Kubernetes.

$ consul-k8s install <OPTIONS>
$ 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.

$ consul-k8s install -preset=secure -namespace=myNS
$ 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.

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

»uninstall

The uninstall command removes Consul from Kubernetes.

$ consul-k8s uninstall <OPTIONS>
$ 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:

$ consul-k8s uninstall -namespace=my-ns -name=my-consul -wipe-data=true -auto-approve=true
$ 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.

$ consul-k8s status
$ consul-k8s status

»Example Command

$ consul-k8s status

==> Consul-K8s Status Summary
   NAME  | NAMESPACE |  STATUS  | CHARTVERSION | APPVERSION | REVISION |      LAST UPDATED
---------+-----------+----------+--------------+------------+----------+--------------------------
  consul | consul    | deployed | 0.41.1       | 1.11.4     |        1 | 2022/03/10 07:48:58 MST

==> Config:
    connectInject:
      enabled: true
      metrics:
        defaultEnableMerging: true
        defaultEnabled: true
        enableGatewayMetrics: true
    controller:
      enabled: true
    global:
      metrics:
        enableAgentMetrics: true
        enabled: true
      name: consul
    prometheus:
      enabled: true
    server:
      replicas: 1
    ui:
      enabled: true
      service:
        enabled: true

 ✓ Consul servers healthy (1/1)
 ✓ Consul clients healthy (3/3)
$ consul-k8s status

==> Consul-K8s Status Summary
   NAME  | NAMESPACE |  STATUS  | CHARTVERSION | APPVERSION | REVISION |      LAST UPDATED
---------+-----------+----------+--------------+------------+----------+--------------------------
  consul | consul    | deployed | 0.41.1       | 1.11.4     |        1 | 2022/03/10 07:48:58 MST

==> Config:
    connectInject:
      enabled: true
      metrics:
        defaultEnableMerging: true
        defaultEnabled: true
        enableGatewayMetrics: true
    controller:
      enabled: true
    global:
      metrics:
        enableAgentMetrics: true
        enabled: true
      name: consul
    prometheus:
      enabled: true
    server:
      replicas: 1
    ui:
      enabled: true
      service:
        enabled: true

 ✓ Consul servers healthy (1/1)
 ✓ 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

$ consul-k8s upgrade
$ 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.

$ consul-k8s version
$ consul-k8s version

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

$ consul-k8s --version
$ 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
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager