adding k8s-cli alpha docs
This commit is contained in:
trujillo-adam
parent
1f23bdf388
commit
cf58cd1e54
|
|
@ -11,7 +11,7 @@ description: >-
|
|||
# Kubernetes
|
||||
|
||||
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 or Consul K8s CLI<sup>ALPHA</sup>, sync services between Consul and
|
||||
Kubernetes, run Consul Connect Service Mesh, and more.
|
||||
This section documents the official integrations between Consul and Kubernetes.
|
||||
|
||||
|
|
|
|||
|
|
@ -15,58 +15,54 @@ For pure-Kubernetes workloads, this enables Consul to also exist purely
|
|||
within Kubernetes. For heterogeneous workloads, Consul agents can join
|
||||
a server running inside or outside of Kubernetes.
|
||||
|
||||
This page starts with a large how-to section for various specific tasks.
|
||||
To learn more about the general architecture of Consul on Kubernetes, scroll
|
||||
down to the [architecture](/docs/k8s/installation/install#architecture) section.
|
||||
If you would like to get hands-on experience testing Consul as a service mesh
|
||||
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.
|
||||
You can install Consul on Kubernetes using the Helm chart or by using the Consul K8s CLI tool <sup>ALPHA</sup>.
|
||||
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
|
||||
|
||||
The recommended way to run Consul on Kubernetes is via the
|
||||
[Helm chart](/docs/k8s/helm). This will install and configure
|
||||
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
|
||||
chart, you can have a full Consul deployment up and running in minutes.
|
||||
to run a server cluster, a client cluster, or both.
|
||||
|
||||
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)
|
||||
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
|
||||
sets up complex resources, it **does not automatically operate Consul.**
|
||||
You are still responsible for learning how to monitor, backup,
|
||||
The Helm chart exposes several useful configurations and automatically
|
||||
sets up complex resources, but it **does not automatically operate Consul.**
|
||||
You must still become familiar with how to monitor, backup,
|
||||
upgrade, etc. the Consul cluster.
|
||||
|
||||
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,
|
||||
it is highly recommended that you
|
||||
[learn about the configuration options](/docs/k8s/helm#configuration-values).
|
||||
cluster with default configurations. We strongly recommend [learning about the configuration options](/docs/k8s/helm#configuration-values) prior to going to production.
|
||||
|
||||
~> **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,
|
||||
but is not appropriate for a production setup. It is highly recommended to use
|
||||
a properly secured Kubernetes cluster or make sure that you understand and enable
|
||||
but is not appropriate for a production setup. We strongly recommend using
|
||||
a properly-secured Kubernetes cluster or making sure that you understand and enable
|
||||
the [recommended security features](/docs/internals/security). Currently,
|
||||
some of these features are not supported in the Helm chart and require additional
|
||||
manual configuration.
|
||||
|
||||
### 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 Consul
|
||||
|
||||
Add the HashiCorp Helm Repository:
|
||||
1. Add the HashiCorp Helm Repository:
|
||||
|
||||
```shell-session
|
||||
$ helm repo add hashicorp https://helm.releases.hashicorp.com
|
||||
"hashicorp" has been added to your repositories
|
||||
```
|
||||
```shell-session
|
||||
$ helm repo add hashicorp https://helm.releases.hashicorp.com
|
||||
"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
|
||||
$ helm search repo hashicorp/consul
|
||||
|
|
@ -83,10 +79,8 @@ NAME: consul
|
|||
...
|
||||
```
|
||||
|
||||
_That's it._ The Helm chart does everything to set up a recommended
|
||||
Consul-on-Kubernetes deployment.
|
||||
In a couple minutes, a Consul cluster will be formed and a leader
|
||||
elected and every node will have a running Consul agent.
|
||||
The Helm chart does everything to set up a recommended Consul-on-Kubernetes deployment.
|
||||
After installation, a Consul cluster will be formed, a will be leader elected, and every node will have a running Consul agent.
|
||||
|
||||
### Customizing Your Installation
|
||||
|
||||
|
|
@ -122,6 +116,45 @@ NAME: consul
|
|||
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.
|
||||
|
||||
## 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 specify the `-auto-approve` option or set the 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
|
||||
|
||||
The Consul UI is enabled by default when using the Helm chart.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,100 @@
|
|||
---
|
||||
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-cli](https://github.com/hashicorp/consul-k8s-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
|
||||
```
|
||||
|
||||
## 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` | 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 |
|
||||
| `-name` | String value for the name of the installation. The specified value will be prefixed to resources installed on the cluster. | 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/> `default`: TODO - DESCRIPTION <br/> `demo`: TODO -DESCRIPTION <br/> `secure`: TODO - DESCRIPTION. | `default` | 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 |
|
||||
|
||||
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 |
|
||||
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -------- | -------- |
|
||||
| `-skip-confirm` | 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 |
|
||||
|
||||
See [Global Options](#global-options) for additional commands that you can use when uninstalling Consul from Kubernetes.
|
||||
|
||||
#### Example Command
|
||||
|
||||
The following example command uninstalls Consul from the `my-ns` namespace with the name `my-consul`.
|
||||
|
||||
```shell-session
|
||||
consul-k8s uninstall -name=my-consul -namespace=my-ns
|
||||
```
|
||||
|
||||
## Global Options
|
||||
|
||||
The following global options are available.
|
||||
|
||||
| Flag | Description | Default | Required |
|
||||
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------- | -------- |
|
||||
| `-context` | String value that sets the Kubernetes context to use for Consul K8s CLI operations. | none | Optional |
|
||||
| `-kubeconfig` | String value that specifies the path to the `kubeconfig` file. <br/> The file is aliased as `-c` | none | Optional |
|
||||
|
|
@ -6,8 +6,11 @@ description: Uninstall Consul on Kubernetes
|
|||
|
||||
# Uninstall Consul
|
||||
|
||||
Uninstalling Consul requires running `helm delete` **and** then manually cleaning
|
||||
up some resources that Helm does not delete.
|
||||
You can uninstall Consul using Helm commands or the Consul K8s CLI.
|
||||
|
||||
## Helm commands
|
||||
|
||||
Run the `helm delete` **and** manually remove resources that Helm does not delete.
|
||||
|
||||
1. First, run `helm delete`:
|
||||
|
||||
|
|
@ -38,31 +41,31 @@ up some resources that Helm does not delete.
|
|||
|
||||
1. If installing with ACLs enabled, you will need to then delete the ACL secrets:
|
||||
|
||||
```shell-session
|
||||
$ kubectl get secret | grep consul | grep Opaque
|
||||
consul-acl-replication-acl-token Opaque 1 41m
|
||||
consul-bootstrap-acl-token Opaque 1 41m
|
||||
consul-client-acl-token Opaque 1 41m
|
||||
consul-connect-inject-acl-token Opaque 1 37m
|
||||
consul-controller-acl-token Opaque 1 37m
|
||||
consul-federation Opaque 4 41m
|
||||
consul-mesh-gateway-acl-token Opaque 1 41m
|
||||
```
|
||||
```shell-session
|
||||
$ kubectl get secret | grep consul | grep Opaque
|
||||
consul-acl-replication-acl-token Opaque 1 41m
|
||||
consul-bootstrap-acl-token Opaque 1 41m
|
||||
consul-client-acl-token Opaque 1 41m
|
||||
consul-connect-inject-acl-token Opaque 1 37m
|
||||
consul-controller-acl-token Opaque 1 37m
|
||||
consul-federation Opaque 4 41m
|
||||
consul-mesh-gateway-acl-token Opaque 1 41m
|
||||
```
|
||||
|
||||
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`.
|
||||
Ensure that the secrets you're about to delete are all created by Consul and not
|
||||
created by another user with the word `consul`.
|
||||
|
||||
```shell-session
|
||||
$ kubectl get secret | grep consul | grep Opaque | awk '{print $1}' | xargs kubectl delete secret
|
||||
secret "consul-acl-replication-acl-token" deleted
|
||||
secret "consul-bootstrap-acl-token" deleted
|
||||
secret "consul-client-acl-token" deleted
|
||||
secret "consul-connect-inject-acl-token" deleted
|
||||
secret "consul-controller-acl-token" deleted
|
||||
secret "consul-federation" deleted
|
||||
secret "consul-mesh-gateway-acl-token" deleted
|
||||
secret "consul-gossip-encryption-key" deleted
|
||||
```
|
||||
```shell-session
|
||||
$ kubectl get secret | grep consul | grep Opaque | awk '{print $1}' | xargs kubectl delete secret
|
||||
secret "consul-acl-replication-acl-token" deleted
|
||||
secret "consul-bootstrap-acl-token" deleted
|
||||
secret "consul-client-acl-token" deleted
|
||||
secret "consul-connect-inject-acl-token" deleted
|
||||
secret "consul-controller-acl-token" deleted
|
||||
secret "consul-federation" deleted
|
||||
secret "consul-mesh-gateway-acl-token" deleted
|
||||
secret "consul-gossip-encryption-key" deleted
|
||||
```
|
||||
|
||||
1. If installing with `controller.enabled` then you will need to delete the
|
||||
webhook certificate:
|
||||
|
|
@ -91,3 +94,13 @@ secret "consul-gossip-encryption-key" deleted
|
|||
$ kubectl delete serviceaccount consul-tls-init
|
||||
serviceaccount "consul-tls-init" deleted
|
||||
```
|
||||
|
||||
## Consul K8s CLI
|
||||
|
||||
Issue the `consul-k8s uninstall` command to remove Consul from Kubernetes.
|
||||
|
||||
```shell-session
|
||||
consul-k8s uninstall <OPTIONS>
|
||||
```
|
||||
|
||||
You can specify the specific installation name, namespace, etc. using the applicable options. Refer to the [Consul K8s CLI reference](/docs/k8s/k8s-cli#uninstall) topic for details.
|
||||
|
|
|
|||
|
|
@ -359,7 +359,7 @@
|
|||
"title": "Get Started",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Install with Helm Chart",
|
||||
"title": "Installing Consul on Kubernetes",
|
||||
"path": "k8s/installation/install"
|
||||
},
|
||||
{
|
||||
|
|
@ -552,6 +552,10 @@
|
|||
{
|
||||
"title": "Helm Chart Configuration",
|
||||
"path": "k8s/helm"
|
||||
},
|
||||
{
|
||||
"title": "Consul K8s CLI Reference",
|
||||
"path": "k8s/k8s-cli"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in New Issue