open-consul/website/content/docs/k8s/k8s-cli.mdx

245 lines
28 KiB
Plaintext
Raw Normal View History

2021-09-14 19:25:24 +00:00
---
layout: docs
page_title: Consul K8s CLI Reference
description: >-
Consul K8s CLI is a tool for quickly installing and interacting with Consul on Kubernetes.
---
# Consul K8s CLI Reference
Consul K8s CLI is a tool for quickly installing and interacting with Consul on Kubernetes.
This topic describes the commands, subcommands, and available options for using Consul K8s CLI.
## Install the Consul K8s CLI
2021-09-14 19:25:24 +00:00
The [Homebrew](https://brew.sh) package manager is required to complete the following installation instructions.
2021-09-14 19:25:24 +00:00
1. Install the HashiCorp `tap`, which is a repository of all Homebrew packages for HashiCorp:
```shell-session
brew tap hashicorp/tap
```
1. Install the Consul K8s CLI with `hashicorp/tap/consul` formula.
```shell-session
brew install hashicorp/tap/consul-k8s
```
2021-09-14 19:25:24 +00:00
1. If you have already provisioned a Kubernetes cluster and have already configured access to the cluster via a `kubeconfig` file, you are ready to install Consul K8s. Issue the `install` subcommand to install Consul on Kubernetes:
```shell-session
consul-k8s install <OPTIONS>
```
2021-09-20 21:40:36 +00:00
1. (Optional) Issue the `consul-k8s version` command to verify the installation:
```shell-session
2021-10-05 01:45:57 +00:00
consul-k8s version
consul-k8s 0.39.0
```
## Upgrade the Consul K8s CLI
The [Homebrew](https://brew.sh) package manager is required to complete the following installation instructions. The `brew upgrade` command assumes that Hashicorp `tap` repository has already been installed from a prior install.
1. Upgrade the Consul K8s CLI with the latest `consul-k8s` package.
```shell-session
brew upgrade consul-k8s
```
2. (Optional) Issue the `consul-k8s version` command to verify the installation:
```shell-session
consul-k8s version
consul-k8s 0.39.0
```
2021-09-14 19:25:24 +00:00
## Usage
Consul K8s CLI uses the following syntax:
```shell-session
consul-k8s <SUBCOMMAND> <OPTIONS>
2021-09-20 21:44:38 +00:00
```
2021-09-14 19:25:24 +00:00
## Subcommands
You can use the following subcommands with `consul-k8s`.
- [install](#install)
- [uninstall](#uninstall)
- [status](#status)
- [upgrade](#upgrade) <sup>BETA</sup>
- [version](#version)
2021-09-14 19:25:24 +00:00
### `install`
The `install` command installs Consul on Kubernetes.
```shell-session
consul-k8s install <OPTIONS>
```
The following options are available.
| Flag | Description | Default | Required |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------- |
| `-auto-approve` &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Boolean value that enables you to skip the installation confirmation prompt. | `false` | Optional |
| `-dry-run` | Boolean value that validates the installation and returns a summary. | `false` | Optional |
| `-config-file` | String value that specifies the path to a file containing custom installation configurations, e.g., Consul Helm chart values file. <br/> You can use the `-config-file` flag multiple times to specify multiple files. | none | Optional |
| `-namespace` | String value that specifies the namespace of the Consul installation. | `consul` | Optional |
| `-preset` | String value that installs Consul based on a preset configuration. You can specify the following values: <br/> `demo`: Installs a single replica server with sidecar injection enabled; useful for testing service mesh functionality. <br/> `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 |
| `-set` | String value that enables you to set a customizeable value. This flag is comparable to the `helm install --set` flag. <br/> You can use the `-set` flag multiple times to set multiple values. <br/> Consul Helm chart values are supported. | none | Optional |
| `-set-file` | String value that specifies the name of an arbitrary config file. This flag is comparable to the `helm install --set-file` <br/> flag. The contents of the file will be used to set a customizeable value. You can use the `-set-file` flag multiple times to specify multiple files. <br/> Consul Helm chart values are supported. | none | Optional |
| `-set-string` | String value that enables you to set a customizeable string value. This flag is comparable to the `helm install --set-string` <br/> flag. You can use the `-set-string` flag multiple times to specify multiple strings. <br/> Consul Helm chart values are supported. | none | Optional |
| `-timeout` | Specifies 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. <br/> The following units are supported: <br/> `ms` (milliseconds)<br/>`s` (seconds)<br/>`m` (minutes) <br/>In the following example, installation will timeout after one minute:<br/> `consul-k8s install -timeout 1m` | `10m` | Optional |
| `-wait` | Boolean value that determines if Consul should wait for resources in the installation to be ready before exiting the command. | `true` | Optional |
| `-verbose`, `-v` | Boolean value that specifies whether to output verbose logs from the install command with the status of resources being installed. | `false` | Optional |
| `--help` | Prints usage information for this option. | none | Optional |
2021-09-14 19:25:24 +00:00
See [Global Options](#global-options) for additional commands that you can use when installing Consul on Kubernetes.
#### Example Commands
2021-09-14 19:25:24 +00:00
The following example command installs Consul according in the `myNS` namespace according to the `secure` preset.
```shell-session
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](https://helm.sh/docs/helm/helm_install/#helm-install).
```shell-session
consul-k8s install -set key=value
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 -set-file config2=value2.conf
consul-k8s install -set-string key=value-bool
consul-k8s install -set key1=value1 -set key2=value2
```
2021-09-14 19:25:24 +00:00
### `uninstall`
The `uninstall` command removes Consul from Kubernetes.
```shell-session
consul-k8s uninstall <OPTIONS>
```
The following options are available.
| Flag | Description | Default | Required |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------- |
| `-auto-approve` &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Boolean value that enables you to skip the removal confirmation prompt. | `false` | Optional |
| `-name` | String value for the name of the installation to remove. | none | Optional |
| `-namespace` | String value that specifies the namespace of the Consul installation to remove. | `consul` | Optional |
| `-timeout` | Specifies 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. <br/> The following units are supported: <br/> `ms` (milliseconds)<br/>`s` (seconds)<br/>`m` (minutes) <br/>`h` (hours) <br/>In the following example, removal will timeout after one minute:<br/> `consul-k8s uninstall -timeout 1m` | `10m` | Optional |
| `-wipe-data` | Boolan value that deletes PVCs and secrets associated with the Consul installation during installation. <br/> Data will be removed without a verification prompt if the `-auto-approve` flag is set to `true`. | `false` <br/> Instructions for removing data will be printed to the console. | Optional |
| `--help` | Prints usage information for this option. | none | Optional |
2021-09-14 19:25:24 +00:00
See [Global Options](#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:
2021-09-14 19:25:24 +00:00
```shell-session
consul-k8s uninstall -namespace=my-ns -name=my-consul -wipe-data=true -auto-approve=true
2021-09-14 19:25:24 +00:00
```
### `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.
```shell-session
consul-k8s status
```
#### Example Command
```shell-session
$ consul-k8s status
==> Consul-K8s Status Summary
NAME | NAMESPACE | STATUS | CHARTVERSION | APPVERSION | REVISION | LAST UPDATED
---------+-----------+----------+--------------+------------+----------+--------------------------
consul | consul | deployed | 0.39.0 | 1.11.1 | 1 | 2021/12/16 15:42:39 PST
==> 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](#upgrade-the-consul-k8s-cli)
```shell-session
consul-k8s upgrade
```
The following options are available.
| Flag | Description | Default | Required |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------- |
| `-auto-approve` &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Boolean value that enables you to skip the upgrade confirmation prompt. | `false` | Optional |
| `-dry-run` | Boolean value that allows you to run pre-upgrade checks and returns a summary of the upgrade. | `false` | Optional |
| `-config-file` | String value that specifies the path to a file containing custom upgrade configurations, e.g., Consul Helm chart values file. <br/> You can use the `-config-file` flag multiple times to specify multiple files. | none | Optional |
| `-namespace` | String value that specifies the namespace of the Consul installation. | `consul` | Optional |
| `-preset` | String value that upgrades Consul based on a preset configuration. | Configuration of the Consul Helm chart. | Optional |
| `-set` | String value that enables you to set a customizeable value. This flag is comparable to the `helm upgrade --set` flag. <br/> You can use the `-set` flag multiple times to set multiple values. <br/> Consul Helm chart values are supported. | none | Optional |
| `-set-file` | String value that specifies the name of an arbitrary config file. This flag is comparable to the `helm upgrade --set-file` <br/> flag. The contents of the file will be used to set a customizeable value. You can use the `-set-file` flag multiple times to specify multiple files. <br/> Consul Helm chart values are supported. | none | Optional |
| `-set-string` | String value that enables you to set a customizeable string value. This flag is comparable to the `helm upgrade --set-string` <br/> flag. You can use the `-set-string` flag multiple times to specify multiple strings. <br/> Consul Helm chart values are supported. | none | Optional |
| `-timeout` | Specifies 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. <br/> The following units are supported: <br/> `ms` (milliseconds)<br/>`s` (seconds)<br/>`m` (minutes) <br/>In the following example, the upgrade will timeout after one minute:<br/> `consul-k8s upgrade -timeout 1m` | `10m` | Optional |
| `-wait` | Boolean value that determines if Consul should wait for resources in the upgtrade to be ready before exiting the command. | `true` | Optional |
| `-verbose`, `-v` | Boolean value that specifies whether to output verbose logs from the upgrade command with the status of resources being upgraded. | `false` | Optional |
| `--help` | Prints usage information for this option. | none | Optional |
See [Global Options](#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.
```shell-session
consul-k8s version
```
You can also print the version with the `--version` flag.
```shell-session
consul-k8s --version
```
2021-09-14 19:25:24 +00:00
## Global Options
The following global options are available.
| Flag | Description | Default | Required |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------- | -------- |
| `-context` &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | String value that sets the Kubernetes context to use for Consul K8s CLI operations. | none | Optional |
| `-kubeconfig` <br/> Alias: `-c` | String value that specifies the path to the `kubeconfig` file. <br/> | none | Optional |