status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #11028 from hashicorp/docs-k8s-cli-alpha 

adding k8s-cli alpha docs
This commit is contained in:
trujillo-adam 2021-09-23 16:35:56 -07:00 committed by GitHub
parent e664dbc352 52f82f2831
commit b22684540e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 271 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/content/docs/k8s/index.mdx
View File

@ -11,7 +11,7 @@ description: >-
# Kubernetes # Kubernetes
Consul has many integrations with Kubernetes. You can deploy Consul Consul has many integrations with Kubernetes. You can deploy Consul
to Kubernetes using the Helm chart, sync services between Consul and to Kubernetes using the [Helm chart](/docs/k8s/installation/install#helm-chart-installation) or [Consul K8s CLI<sup>ALPHA</sup>](docs/k8s/installation/install#consul-k8s-cli-installation), sync services between Consul and
Kubernetes, run Consul Connect Service Mesh, and more. Kubernetes, run Consul Connect Service Mesh, and more.
This section documents the official integrations between Consul and Kubernetes. This section documents the official integrations between Consul and Kubernetes.

122
website/content/docs/k8s/installation/install.mdx
View File

@ -15,78 +15,75 @@ For pure-Kubernetes workloads, this enables Consul to also exist purely
within Kubernetes. For heterogeneous workloads, Consul agents can join within Kubernetes. For heterogeneous workloads, Consul agents can join
a server running inside or outside of Kubernetes. a server running inside or outside of Kubernetes.
This page starts with a large how-to section for various specific tasks. You can install Consul on Kubernetes using the following methods:
To learn more about the general architecture of Consul on Kubernetes, scroll
down to the [architecture](/docs/k8s/installation/install#architecture) section. 1. [Helm chart install](#helm-chart-installation)
If you would like to get hands-on experience testing Consul as a service mesh 1. [Consul K8s CLI install <sup>ALPHA</sup>.](#consul-k8s-cli-installation)
for Kubernetes, check the guides in the [Getting Started with Consul service
mesh](https://learn.hashicorp.com/tutorials/consul/service-mesh-deploy?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) track. Refer to the [architecture](/docs/k8s/installation/install#architecture) section to learn more about the general architecture of Consul on Kubernetes.
For a hands-on experience with Consul as a service mesh
for Kubernetes, follow the [Getting Started with Consul service
mesh](https://learn.hashicorp.com/tutorials/consul/service-mesh-deploy?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
## Helm Chart Installation ## Helm Chart Installation
The recommended way to run Consul on Kubernetes is via the The recommended way to run Consul on Kubernetes is via the
[Helm chart](/docs/k8s/helm). This will install and configure [Helm chart](/docs/k8s/helm). This will install and configure
all the necessary components to run Consul. The configuration enables you all the necessary components to run Consul. The configuration enables you
to run just a server cluster, just a client cluster, or both. Using the Helm to run a server cluster, a client cluster, or both.
chart, you can have a full Consul deployment up and running in minutes.
Step-by-step tutorials for how to deploy Consul to Kubernetes, please see Step-by-step tutorials for how to deploy Consul to Kubernetes, please see
our [Deploy to Kubernetes](https://learn.hashicorp.com/collections/consul/kubernetes-deploy) our [Deploy to Kubernetes](https://learn.hashicorp.com/collections/consul/kubernetes-deploy)
collection. This collection includes configuration caveats for single node deployments. collection. This collection includes configuration caveats for single-node deployments.
While the Helm chart exposes dozens of useful configurations and automatically The Helm chart exposes several useful configurations and automatically
sets up complex resources, it **does not automatically operate Consul.** sets up complex resources, but it **does not automatically operate Consul.**
You are still responsible for learning how to monitor, backup, You must still become familiar with how to monitor, backup,
upgrade, etc. the Consul cluster. upgrade, etc. the Consul cluster.
The Helm chart has no required configuration and will install a Consul The Helm chart has no required configuration and will install a Consul
cluster with reasonable defaults out of the box. Prior to going to production, cluster with default configurations. We strongly recommend [learning about the configuration options](/docs/k8s/helm#configuration-values) prior to going to production.
it is highly recommended that you
[learn about the configuration options](/docs/k8s/helm#configuration-values).
~> **Security Warning:** By default, the chart will install an insecure configuration ~> **Security Warning:** By default, the chart will install an insecure configuration
of Consul. This provides a less complicated out-of-box experience for new users, of Consul. This provides a less complicated out-of-box experience for new users,
but is not appropriate for a production setup. It is highly recommended to use but is not appropriate for a production setup. We strongly recommend using
a properly secured Kubernetes cluster or make sure that you understand and enable a properly-secured Kubernetes cluster or making sure that you understand and enable
the [recommended security features](/docs/internals/security). Currently, the [recommended security features](/docs/internals/security). Currently,
some of these features are not supported in the Helm chart and require additional some of these features are not supported in the Helm chart and require additional
manual configuration. manual configuration.
### Prerequisites ### Prerequisites
The Consul Helm chart works only with Helm 3. Install the latest version of the Helm CLI here: The Consul Helm only supports Helm 3. Install the latest version of the Helm CLI here:
[Installing Helm](https://helm.sh/docs/intro/install/). [Installing Helm](https://helm.sh/docs/intro/install/).
### Installing Consul ### Installing Consul
Add the HashiCorp Helm Repository: 1. Add the HashiCorp Helm Repository:
```shell-session ```shell-session
$ helm repo add hashicorp https://helm.releases.hashicorp.com $ helm repo add hashicorp https://helm.releases.hashicorp.com
"hashicorp" has been added to your repositories "hashicorp" has been added to your repositories
``` ```
Ensure you have access to the consul chart: 1. Verify that you have access to the consul chart:
```shell-session ```shell-session
$ helm search repo hashicorp/consul $ helm search repo hashicorp/consul
NAME CHART VERSION APP VERSION DESCRIPTION NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/consul 0.32.0 1.10.0 Official HashiCorp Consul Chart hashicorp/consul 0.32.0 1.10.0 Official HashiCorp Consul Chart
``` ```
Now you're ready to install Consul! To install Consul with the default 1. Issue the following command to install Consul with the default configuration using Helm 3:
configuration using Helm 3 run:
```shell-session ```shell-session
$ helm install consul hashicorp/consul --set global.name=consul $ helm install consul hashicorp/consul --set global.name=consul
NAME: consul NAME: consul
... ...
``` ```
_That's it._ The Helm chart does everything to set up a recommended The Helm chart does everything to set up a recommended Consul-on-Kubernetes deployment.
Consul-on-Kubernetes deployment. After installation, a Consul cluster will be formed, a leader will be elected, and every node will have a running Consul agent.
In a couple minutes, a Consul cluster will be formed and a leader
elected and every node will have a running Consul agent.
### Customizing Your Installation ### Customizing Your Installation
@ -102,11 +99,11 @@ use the following config file:
```yaml ```yaml
global: global:
name: consul name: consul
connectInject: connectInject:
enabled: true enabled: true
controller: controller:
enabled: true enabled: true
``` ```
</CodeBlockConfig> </CodeBlockConfig>
@ -122,6 +119,45 @@ NAME: consul
If you've already installed Consul and want to make changes, you'll need to run If you've already installed Consul and want to make changes, you'll need to run
`helm upgrade`. See [Upgrading](/docs/k8s/operations/upgrading) for more details. `helm upgrade`. See [Upgrading](/docs/k8s/operations/upgrading) for more details.
## Consul K8s CLI Installation
You can install Consul on Kubernetes using the Consul K8s CLI tool.
The tool is currently availabe as an alpha release and is not recommended for production environments.
1. Download and build the CLI as described in the [Consul K8s CLI reference](/docs/k8s/k8s-cli).
1. Issue the `install` subcommand to install Consul on Kubernetes:
```shell-session
consul-k8s install <OPTIONS>
```
Refer to the [Consul K8s CLI reference](/docs/k8s/k8s-cli) for details about all commands and available options.
If you did not set the `-auto-approve` option to `true`, you will be prompted to proceed with the installation if the pre-install checks pass.
```shell-session
==> Pre-Install Checks
✓ No existing installations found
✓ No previous persistent volume claims found
✓ No previous secrets found
==> Consul Installation Summary
Installation name: consul
Namespace: myns
Overrides:
connectInject:
enabled: true
global:
name: consul
server:
bootstrapExpect: 1
replicas: 1
Proceed with installation? (y/n)
```
1. Enter `y` to proceed. The pre-install checks may fail if existing `PersistentVolumeClaims` (PVC) are detected. Refer to the [uninstall instructions](/docs/k8s/operations/uninstall#uninstall-consul) for information about removing PVCs.
## Viewing the Consul UI ## Viewing the Consul UI
The Consul UI is enabled by default when using the Helm chart. The Consul UI is enabled by default when using the Helm chart.

110
website/content/docs/k8s/k8s-cli.mdx Normal file
View File

@ -0,0 +1,110 @@
---
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.
~> Consul K8s CLI is is currently availabe as an alpha release and is not recommended for production environments.
## Download and Build the Binary
1. Clone the [consul-k8s](https://github.com/hashicorp/consul-k8s/tree/cli-install/cli) project.
1. Navigate to the `consul-k8s/cli` directory and issue the following command to build the tool:
```shell-session
go build -o bin/consul-k8s
```
1. (Optional) Move the binary to you `$PATH` for ease of use, e.g.:
```shell-session
mv consul-k8s /usr/local/bin/consul-k8s
```
## Usage
Consul K8s CLI uses the following syntax:
```shell-session
consul-k8s <SUBCOMMAND> <OPTIONS>
```
## Subcommands
You can use the following subcommands with `consul-k8s`.
### `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. <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 a file. The contents of the file will be used to set a customizeable value. <br/> 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. <br/> 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` | Optional | `10m` |
| `-wait` | Boolean value that determines if Consul should wait for resources in the installation to be ready before exiting the command. | Optional | `true` |
See [Global Options](#global-options) for additional commands that you can use when installing Consul on Kubernetes.
#### Example Command
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
```
### `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` | Optional | `10m` |
| `-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 |
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:
```shell-session
consul-k8s uninstall -namespace=my-ns -name=my-consul -wipe-data=true -auto-approve=true
```
## 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 |

41
website/content/docs/k8s/operations/uninstall.mdx
View File

@ -6,19 +6,21 @@ description: Uninstall Consul on Kubernetes
# Uninstall Consul # Uninstall Consul
Uninstalling Consul requires running `helm delete` **and** then manually cleaning You can uninstall Consul using Helm commands or the Consul K8s CLI.
up some resources that Helm does not delete.
1. First, run `helm delete`: ## Helm commands
Run the `helm uninstall` **and** manually remove resources that Helm does not delete.
1. First, run `helm uninstall`:
```shell-session ```shell-session
$ helm delete hashicorp $ helm uninstall hashicorp
release "hashicorp" uninstalled release "hashicorp" uninstalled
``` ```
2. After deleting the Helm release, you need to delete the `PersistentVolumeClaim`'s 1. After deleting the Helm release, you need to delete the `PersistentVolumeClaim`'s
for the persistent volumes that store Consul's data. These are not deleted by Helm due to a [bug](https://github.com/helm/helm/issues/5156). for the persistent volumes that store Consul's data. A [bug](https://github.com/helm/helm/issues/5156) in Helm prevents PVCs from being deleted. Issue the following commands:
To delete, run:
```shell-session ```shell-session
$ kubectl get pvc -l chart=consul-helm $ kubectl get pvc -l chart=consul-helm
@ -36,7 +38,7 @@ up some resources that Helm does not delete.
~> **NOTE:** This will delete **all** data stored in Consul and it can't be ~> **NOTE:** This will delete **all** data stored in Consul and it can't be
recovered unless you've taken other backups. recovered unless you've taken other backups.
3. If installing with ACLs enabled, you will need to then delete the ACL secrets: 1. If installing with ACLs enabled, you will need to then delete the ACL secrets:
```shell-session ```shell-session
$ kubectl get secret | grep consul | grep Opaque $ kubectl get secret | grep consul | grep Opaque
@ -49,8 +51,8 @@ up some resources that Helm does not delete.
consul-mesh-gateway-acl-token Opaque 1 41m consul-mesh-gateway-acl-token Opaque 1 41m
``` ```
4. Ensure that the secrets you're about to delete are all created by Consul and not 1. Ensure that the secrets you're about to delete are all created by Consul and not
created by someone else that happen to have the word `consul`: created by another user with the word `consul`.
```shell-session ```shell-session
$ kubectl get secret | grep consul | grep Opaque | awk '{print $1}' | xargs kubectl delete secret $ kubectl get secret | grep consul | grep Opaque | awk '{print $1}' | xargs kubectl delete secret
@ -64,7 +66,7 @@ up some resources that Helm does not delete.
secret "consul-gossip-encryption-key" deleted secret "consul-gossip-encryption-key" deleted
``` ```
5. If installing with `tls.enabled` then there will be a `ServiceAccount` that is left behind: 1. If installing with `tls.enabled` then, run the following commands to delete the `ServiceAccount` left behind:
```shell-session ```shell-session
$ kubectl get serviceaccount consul-tls-init $ kubectl get serviceaccount consul-tls-init
@ -76,3 +78,20 @@ up some resources that Helm does not delete.
$ kubectl delete serviceaccount consul-tls-init $ kubectl delete serviceaccount consul-tls-init
serviceaccount "consul-tls-init" deleted serviceaccount "consul-tls-init" deleted
``` ```
## Consul K8s CLI
Issue the `consul-k8s uninstall` command to remove Consul on Kubernetes. You can specify the installation name, namespace, and data retention behavior using the applicable options. By default, the uninstallation preserves the secrets and PVCs that are provisioned by Consul on Kubernetes.
```shell-session
$ consul-k8s uninstall <OPTIONS>
```
In the following example, Consul will be uninstalled and the data removed without prompting you to verify the operations:
```shell-session
$ consul-k8s uninstall -auto-approve=true -wipe-data=true
```
Refer to the [Consul K8s CLI reference](/docs/k8s/k8s-cli#uninstall) topic for details.

6
website/data/docs-nav-data.json
View File

@ -359,7 +359,7 @@
"title": "Get Started", "title": "Get Started",
"routes": [ "routes": [
{ {
"title": "Install with Helm Chart", "title": "Installing Consul on Kubernetes",
"path": "k8s/installation/install" "path": "k8s/installation/install"
}, },
{ {
@ -552,6 +552,10 @@
{ {
"title": "Helm Chart Configuration", "title": "Helm Chart Configuration",
"path": "k8s/helm" "path": "k8s/helm"
},
{
"title": "Consul K8s CLI Reference",
"path": "k8s/k8s-cli"
} }
] ]
}, },