From e35236a0532241744db1652455b3c985fc63eb48 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 14 Sep 2021 12:25:24 -0700 Subject: [PATCH 01/18] adding k8s-cli alpha docs --- website/content/docs/k8s/index.mdx | 2 +- .../content/docs/k8s/installation/install.mdx | 89 +++++++++++----- website/content/docs/k8s/k8s-cli.mdx | 100 ++++++++++++++++++ .../content/docs/k8s/operations/uninstall.mdx | 63 ++++++----- website/data/docs-nav-data.json | 6 +- 5 files changed, 205 insertions(+), 55 deletions(-) create mode 100644 website/content/docs/k8s/k8s-cli.mdx diff --git a/website/content/docs/k8s/index.mdx b/website/content/docs/k8s/index.mdx index ef208aac44..e820c2d740 100644 --- a/website/content/docs/k8s/index.mdx +++ b/website/content/docs/k8s/index.mdx @@ -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 CLIALPHA, sync services between Consul and Kubernetes, run Consul Connect Service Mesh, and more. This section documents the official integrations between Consul and Kubernetes. diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index 71068a087f..e66e95f9a3 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -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 ALPHA. +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 + ``` + + 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. diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx new file mode 100644 index 0000000000..fbcd42508f --- /dev/null +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -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 +``` + +## Subcommands + +You can use the following subcommands with `consul-k8s`. + +### `install` + +The `install` command installs Consul on Kubernetes. + +```shell-session +consul-k8s install +``` + +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:
`default`: TODO - DESCRIPTION
`demo`: TODO -DESCRIPTION
`secure`: TODO - DESCRIPTION. | `default` | Optional | +| `-set` | String value that enables you to set a customizeable value.
You can use the `-set` flag multiple times to set multiple values.
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.
You can use the `-set-file` flag multiple times to specify multiple files.
Consul Helm chart values are supported. | none | Optional | +| `-set-string` | String value that enables you to set a customizeable string value.
You can use the `-set-string` flag multiple times to specify multiple strings.
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 +``` + +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.
The file is aliased as `-c` | none | Optional | diff --git a/website/content/docs/k8s/operations/uninstall.mdx b/website/content/docs/k8s/operations/uninstall.mdx index b86dbc7955..bc27c6a040 100644 --- a/website/content/docs/k8s/operations/uninstall.mdx +++ b/website/content/docs/k8s/operations/uninstall.mdx @@ -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 +``` + +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. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 5b27cffc1f..10d529c31e 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -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" } ] }, From dfb4775712b1c0faa42c09afcdfd2f60309f9422 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 15 Sep 2021 11:55:14 -0700 Subject: [PATCH 02/18] updates to the uninstall flags, preset descriptions --- website/content/docs/k8s/k8s-cli.mdx | 32 +++++++++++++++------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index fbcd42508f..7b504e22d4 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -43,16 +43,16 @@ consul-k8s install 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:
`default`: TODO - DESCRIPTION
`demo`: TODO -DESCRIPTION
`secure`: TODO - DESCRIPTION. | `default` | Optional | -| `-set` | String value that enables you to set a customizeable value.
You can use the `-set` flag multiple times to set multiple values.
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.
You can use the `-set-file` flag multiple times to specify multiple files.
Consul Helm chart values are supported. | none | Optional | -| `-set-string` | String value that enables you to set a customizeable string value.
You can use the `-set-string` flag multiple times to specify multiple strings.
Consul Helm chart values are supported. | none | Optional | +| 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:
`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 | +| `-set` | String value that enables you to set a customizeable value.
You can use the `-set` flag multiple times to set multiple values.
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.
You can use the `-set-file` flag multiple times to specify multiple files.
Consul Helm chart values are supported. | none | Optional | +| `-set-string` | String value that enables you to set a customizeable string value.
You can use the `-set-string` flag multiple times to specify multiple strings.
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. @@ -74,11 +74,13 @@ consul-k8s uninstall 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 | +| 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 | +| `-auto-approve-wipe-data` | Boolan value that disables the prompt verifying that PVCs, secrets, and service accounts associated with the Consul installation _will be deleted_.
This flag cannot be applied if `auto-approve-skip-wipe-data` is also used. | `false`
A prompt will appear verifying that you want to delete data. | Optional | +| `-auto-approve-skip-wipe-data` | Boolan value that disables the prompt verifying that PVCs, secrets, and service accounts associated with the Consul installation _will be retained_.
This flag cannot be applied if `auto-approve-wipe-data` is also used. | `false`
A prompt will appear verifying that you want to delete data. | Optional | See [Global Options](#global-options) for additional commands that you can use when uninstalling Consul from Kubernetes. From a25a30921a9f15846031cd67e2ef24262d78e6f0 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 15 Sep 2021 11:59:30 -0700 Subject: [PATCH 03/18] added a few more nbsp to improve table readability --- website/content/docs/k8s/k8s-cli.mdx | 34 ++++++++++++++-------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 7b504e22d4..8f0a3c1f79 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -43,16 +43,16 @@ consul-k8s install 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:
`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 | -| `-set` | String value that enables you to set a customizeable value.
You can use the `-set` flag multiple times to set multiple values.
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.
You can use the `-set-file` flag multiple times to specify multiple files.
Consul Helm chart values are supported. | none | Optional | -| `-set-string` | String value that enables you to set a customizeable string value.
You can use the `-set-string` flag multiple times to specify multiple strings.
Consul Helm chart values are supported. | none | Optional | +| 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:
`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 | +| `-set` | String value that enables you to set a customizeable value.
You can use the `-set` flag multiple times to set multiple values.
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.
You can use the `-set-file` flag multiple times to specify multiple files.
Consul Helm chart values are supported. | none | Optional | +| `-set-string` | String value that enables you to set a customizeable string value.
You can use the `-set-string` flag multiple times to specify multiple strings.
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. @@ -74,13 +74,13 @@ consul-k8s uninstall 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 | -| `-auto-approve-wipe-data` | Boolan value that disables the prompt verifying that PVCs, secrets, and service accounts associated with the Consul installation _will be deleted_.
This flag cannot be applied if `auto-approve-skip-wipe-data` is also used. | `false`
A prompt will appear verifying that you want to delete data. | Optional | -| `-auto-approve-skip-wipe-data` | Boolan value that disables the prompt verifying that PVCs, secrets, and service accounts associated with the Consul installation _will be retained_.
This flag cannot be applied if `auto-approve-wipe-data` is also used. | `false`
A prompt will appear verifying that you want to delete data. | Optional | +| 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 | +| `-auto-approve-wipe-data` | Boolan value that disables the prompt verifying that PVCs, secrets, and service accounts associated with the Consul installation _will be deleted_.
This flag cannot be applied if `auto-approve-skip-wipe-data` is also used. | `false`
A prompt will appear verifying that you want to delete data. | Optional | +| `-auto-approve-skip-wipe-data`                                                       | Boolan value that disables the prompt verifying that PVCs, secrets, and service accounts associated with the Consul installation _will be retained_.
This flag cannot be applied if `auto-approve-wipe-data` is also used. | `false`
A prompt will appear verifying that you want to delete data. | Optional | See [Global Options](#global-options) for additional commands that you can use when uninstalling Consul from Kubernetes. From 5987900fd3f60191b99a0ed7d31ab8a6a57d2ed8 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Wed, 15 Sep 2021 20:30:58 -0700 Subject: [PATCH 04/18] Update website/content/docs/k8s/installation/install.mdx Co-authored-by: Nitya Dhanushkodi --- website/content/docs/k8s/installation/install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index e66e95f9a3..d281620b8e 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -80,7 +80,7 @@ NAME: consul ``` 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. +After installation, a Consul cluster will be formed, a leader will be elected, and every node will have a running Consul agent. ### Customizing Your Installation From b8d1e205cd8a290dbebabe97fa9acd329119188e Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Wed, 15 Sep 2021 20:31:17 -0700 Subject: [PATCH 05/18] Update website/content/docs/k8s/index.mdx Co-authored-by: Nitya Dhanushkodi --- website/content/docs/k8s/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/k8s/index.mdx b/website/content/docs/k8s/index.mdx index e820c2d740..8ba7cc9b5b 100644 --- a/website/content/docs/k8s/index.mdx +++ b/website/content/docs/k8s/index.mdx @@ -11,7 +11,7 @@ description: >- # Kubernetes Consul has many integrations with Kubernetes. You can deploy Consul -to Kubernetes using the Helm chart or Consul K8s CLIALPHA, sync services between Consul and +to Kubernetes using the [Helm chart](/docs/k8s/installation/install#helm-chart-installation) or [Consul K8s CLIALPHA](docs/k8s/installation/install#consul-k8s-cli-installation), sync services between Consul and Kubernetes, run Consul Connect Service Mesh, and more. This section documents the official integrations between Consul and Kubernetes. From 470fba1a0e1c45762e25f788815201013ccb2529 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Wed, 15 Sep 2021 20:31:43 -0700 Subject: [PATCH 06/18] Update website/content/docs/k8s/installation/install.mdx Co-authored-by: Nitya Dhanushkodi --- website/content/docs/k8s/installation/install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index d281620b8e..1f1dfcf0a0 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -130,7 +130,7 @@ The tool is currently availabe as an alpha release and is not recommended for pr 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. + 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 From ef9c1776dd814c2ffa2a9b2ef8412f659f20619a Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Wed, 15 Sep 2021 20:32:21 -0700 Subject: [PATCH 07/18] Update website/content/docs/k8s/k8s-cli.mdx Co-authored-by: Nitya Dhanushkodi --- website/content/docs/k8s/k8s-cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 8f0a3c1f79..41cf44bf87 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -99,4 +99,4 @@ 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.
The file is aliased as `-c` | none | Optional | +| `-kubeconfig`
Alias: `-c` | String value that specifies the path to the `kubeconfig` file.
| none | Optional | From bacd9423e0aded99828bacff75aa2ac2e270aabc Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 16 Sep 2021 09:54:55 -0700 Subject: [PATCH 08/18] removed flag, added flag, and applied feedback --- website/content/docs/k8s/installation/install.mdx | 5 ++--- website/content/docs/k8s/k8s-cli.mdx | 14 ++++++++++---- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index e66e95f9a3..cccfdcab81 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -70,8 +70,7 @@ NAME CHART VERSION APP VERSION DESCRIPTION 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 -configuration using Helm 3 run: +1. Issue the following command to install Consul with the default configuration using Helm 3: ```shell-session $ helm install consul hashicorp/consul --set global.name=consul @@ -80,7 +79,7 @@ NAME: consul ``` 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. +After installation, a Consul cluster will be formed, a leader will be elected, and every node will have a running Consul agent. ### Customizing Your Installation diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 8f0a3c1f79..7c37d2ce6a 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -14,13 +14,19 @@ This topic describes the commands, subcommands, and available options for using ## 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: +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 + go build . ``` +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: @@ -47,7 +53,7 @@ The following options are available. | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------- | | `-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 | +| `-config-file` | String 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. | 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:
`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 | | `-set` | String value that enables you to set a customizeable value.
You can use the `-set` flag multiple times to set multiple values.
Consul Helm chart values are supported. | none | Optional | From 183b02176796726f9e3ea2292a8a59b0616a91ef Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 16 Sep 2021 16:32:13 -0700 Subject: [PATCH 09/18] applied additional feedback, updated uninstall flags --- .../content/docs/k8s/installation/install.mdx | 24 ++++++++++-------- website/content/docs/k8s/k8s-cli.mdx | 25 +++++++++---------- .../content/docs/k8s/operations/uninstall.mdx | 12 +++++++-- 3 files changed, 36 insertions(+), 25 deletions(-) diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index b44aefced9..859e752e10 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -15,7 +15,11 @@ 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. -You can install Consul on Kubernetes using the Helm chart or by using the Consul K8s CLI tool ALPHA. +You can install Consul on Kubernetes using the following methods: + +1. [Helm chart install](#helm-chart-installation) +1. [Consul K8s CLI install ALPHA.](#consul-k8s-cli-installation) + 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 @@ -72,11 +76,11 @@ hashicorp/consul 0.32.0 1.10.0 Official HashiCorp Consul Chart 1. Issue the following command to install Consul with the default configuration using Helm 3: -```shell-session -$ helm install consul hashicorp/consul --set global.name=consul -NAME: consul -... -``` +````shell-session + $ helm install consul hashicorp/consul --set global.name=consul + NAME: consul + ... + ``` The Helm chart does everything to set up a recommended 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. @@ -95,12 +99,12 @@ use the following config file: ```yaml global: - name: consul +name: consul connectInject: - enabled: true +enabled: true controller: - enabled: true -``` +enabled: true +```` diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 166356a097..19d06b75ca 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -80,29 +80,28 @@ consul-k8s uninstall 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 | -| `-auto-approve-wipe-data` | Boolan value that disables the prompt verifying that PVCs, secrets, and service accounts associated with the Consul installation _will be deleted_.
This flag cannot be applied if `auto-approve-skip-wipe-data` is also used. | `false`
A prompt will appear verifying that you want to delete data. | Optional | -| `-auto-approve-skip-wipe-data`                                                       | Boolan value that disables the prompt verifying that PVCs, secrets, and service accounts associated with the Consul installation _will be retained_.
This flag cannot be applied if `auto-approve-wipe-data` is also used. | `false`
A prompt will appear verifying that you want to delete data. | Optional | +| Flag | Description | Default | Required | +| --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------- | +| `-auto-approve`                                     | 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 | +| `-wipe-data` | Boolan 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 | 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`. +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 -name=my-consul -namespace=my-ns +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`                   | String value that sets the Kubernetes context to use for Consul K8s CLI operations. | none | Optional | -| `-kubeconfig`
Alias: `-c` | String value that specifies the path to the `kubeconfig` file.
| none | Optional | +| Flag | Description | Default | Required | +| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------- | -------- | +| `-context`                   | String value that sets the Kubernetes context to use for Consul K8s CLI operations. | none | Optional | +| `-kubeconfig`
Alias: `-c` | String value that specifies the path to the `kubeconfig` file.
| none | Optional | diff --git a/website/content/docs/k8s/operations/uninstall.mdx b/website/content/docs/k8s/operations/uninstall.mdx index bc27c6a040..2fab0f98f8 100644 --- a/website/content/docs/k8s/operations/uninstall.mdx +++ b/website/content/docs/k8s/operations/uninstall.mdx @@ -100,7 +100,15 @@ Run the `helm delete` **and** manually remove resources that Helm does not delet Issue the `consul-k8s uninstall` command to remove Consul from Kubernetes. ```shell-session -consul-k8s uninstall +$ consul-k8s uninstall ``` -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. +You can specify the installation name, namespace, and data retention behavior using the applicable 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. From 2cc678d388953c4f1d555a792d5c10f994704f3a Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Sep 2021 09:31:19 -0700 Subject: [PATCH 10/18] fixing some syntax errors that didn't appear locally --- website/content/docs/k8s/installation/install.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index 859e752e10..28d5b56d35 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -69,15 +69,15 @@ The Consul Helm only supports Helm 3. Install the latest version of the Helm CLI 1. Verify that you have access to the consul chart: ```shell-session -$ helm search repo hashicorp/consul -NAME CHART VERSION APP VERSION DESCRIPTION -hashicorp/consul 0.32.0 1.10.0 Official HashiCorp Consul Chart + $ helm search repo hashicorp/consul + NAME CHART VERSION APP VERSION DESCRIPTION + hashicorp/consul 0.32.0 1.10.0 Official HashiCorp Consul Chart ``` 1. Issue the following command to install Consul with the default configuration using Helm 3: ````shell-session - $ helm install consul hashicorp/consul --set global.name=consul +$ helm install consul hashicorp/consul --set global.name=consul NAME: consul ... ``` From 0722e17e93b180c4a36d703e342c7dd92de1728b Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Sep 2021 15:11:10 -0700 Subject: [PATCH 11/18] updating the helm uninstall instructions --- .../content/docs/k8s/operations/uninstall.mdx | 28 ++++--------------- 1 file changed, 6 insertions(+), 22 deletions(-) diff --git a/website/content/docs/k8s/operations/uninstall.mdx b/website/content/docs/k8s/operations/uninstall.mdx index 2fab0f98f8..09afd457f0 100644 --- a/website/content/docs/k8s/operations/uninstall.mdx +++ b/website/content/docs/k8s/operations/uninstall.mdx @@ -10,18 +10,17 @@ 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. +Run the `helm uninstall` **and** manually remove resources that Helm does not delete. -1. First, run `helm delete`: +1. First, run `helm uninstall`: ```shell-session - $ helm delete hashicorp + $ helm uninstall hashicorp release "hashicorp" uninstalled ``` 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). - To delete, run: + 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: ```shell-session $ kubectl get pvc -l chart=consul-helm @@ -52,7 +51,7 @@ Run the `helm delete` **and** manually remove resources that Helm does not delet consul-mesh-gateway-acl-token Opaque 1 41m ``` - 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 another user with the word `consul`. ```shell-session @@ -67,22 +66,7 @@ Run the `helm delete` **and** manually remove resources that Helm does not delet secret "consul-gossip-encryption-key" deleted ``` -1. If installing with `controller.enabled` then you will need to delete the - webhook certificate: - - ```shell-session - $ kubectl get secret consul-controller-webhook-cert - NAME TYPE DATA AGE - consul-controller-webhook-cert kubernetes.io/tls 2 47m - ``` - - ```shell-session - $ kubectl delete secret consul-controller-webhook-cert - secret "consul-consul-controller-webhook-cert" deleted - ``` - -1. 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 $ kubectl get serviceaccount consul-tls-init From faee67e35b7104620687b6efc790981c86f518da Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 20 Sep 2021 10:19:27 -0700 Subject: [PATCH 12/18] removed extra codeblock tic --- website/content/docs/k8s/installation/install.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index 28d5b56d35..4f9d2083c6 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -76,11 +76,11 @@ The Consul Helm only supports Helm 3. Install the latest version of the Helm CLI 1. Issue the following command to install Consul with the default configuration using Helm 3: -````shell-session +```shell-session $ helm install consul hashicorp/consul --set global.name=consul NAME: consul ... - ``` +``` The Helm chart does everything to set up a recommended 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. @@ -104,7 +104,7 @@ connectInject: enabled: true controller: enabled: true -```` +``` From c6eae6858c4af6d408600798da67969458f74704 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 20 Sep 2021 10:25:06 -0700 Subject: [PATCH 13/18] fixed indentation on install page --- .../content/docs/k8s/installation/install.mdx | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index 4f9d2083c6..9afe1dd035 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -68,19 +68,21 @@ The Consul Helm only supports Helm 3. Install the latest version of the Helm CLI 1. Verify that you have access to the consul chart: -```shell-session - $ helm search repo hashicorp/consul - NAME CHART VERSION APP VERSION DESCRIPTION - hashicorp/consul 0.32.0 1.10.0 Official HashiCorp Consul Chart -``` + ```shell-session + $ helm search repo hashicorp/consul + NAME CHART VERSION APP VERSION DESCRIPTION + hashicorp/consul 0.32.0 1.10.0 Official HashiCorp Consul Chart + ``` 1. Issue the following command to install Consul with the default configuration using Helm 3: -```shell-session -$ helm install consul hashicorp/consul --set global.name=consul - NAME: consul - ... -``` + ```shell-session + $ helm install consul hashicorp/consul --set global.name=consul + NAME: consul + ... + ``` + +```` The Helm chart does everything to set up a recommended 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. @@ -104,7 +106,7 @@ connectInject: enabled: true controller: enabled: true -``` +```` From 9863054362de0bfeadaf1dba48b72b2b1e5db345 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 20 Sep 2021 11:04:04 -0700 Subject: [PATCH 14/18] removed extra codeblock ticks --- website/content/docs/k8s/installation/install.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index 9afe1dd035..0ea21bb260 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -82,8 +82,6 @@ The Consul Helm only supports Helm 3. Install the latest version of the Helm CLI ... ``` -```` - The Helm chart does everything to set up a recommended 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. @@ -106,7 +104,7 @@ connectInject: enabled: true controller: enabled: true -```` +``` From 4aa40ccbe11c91f8ee00ef34ec61296b9ab28a13 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Mon, 20 Sep 2021 14:38:51 -0700 Subject: [PATCH 15/18] Apply suggestions from code review Co-authored-by: David Yu --- website/content/docs/k8s/operations/uninstall.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/content/docs/k8s/operations/uninstall.mdx b/website/content/docs/k8s/operations/uninstall.mdx index 09afd457f0..f570b0e351 100644 --- a/website/content/docs/k8s/operations/uninstall.mdx +++ b/website/content/docs/k8s/operations/uninstall.mdx @@ -81,13 +81,12 @@ Run the `helm uninstall` **and** manually remove resources that Helm does not de ## Consul K8s CLI -Issue the `consul-k8s uninstall` command to remove Consul from Kubernetes. +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 ``` -You can specify the installation name, namespace, and data retention behavior using the applicable options. In the following example, Consul will be uninstalled and the data removed without prompting you to verify the operations: From bf7204673787f8b293c4bb36f9ac614e1124552c Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 20 Sep 2021 14:40:36 -0700 Subject: [PATCH 16/18] fixed formatting --- website/content/docs/k8s/k8s-cli.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 19d06b75ca..95725ccb5f 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -23,9 +23,11 @@ This topic describes the commands, subcommands, and available options for using 1. (Optional) Move the binary to you `$PATH` for ease of use, e.g.: -```shell-session -mv consul-k8s /usr/local/bin/consul-k8s -``` + ```shell-session + mv consul-k8s /usr/local/bin/consul-k8s + ``` + +```` ## Usage @@ -33,7 +35,7 @@ Consul K8s CLI uses the following syntax: ```shell-session consul-k8s -``` +```` ## Subcommands From f0815f9cc2179d6940d1348b5c917f54e1cbd385 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 20 Sep 2021 14:44:38 -0700 Subject: [PATCH 17/18] removed extra codeblock ticks, again --- website/content/docs/k8s/k8s-cli.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 95725ccb5f..221de10821 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -27,15 +27,13 @@ This topic describes the commands, subcommands, and available options for using mv consul-k8s /usr/local/bin/consul-k8s ``` -```` - ## Usage Consul K8s CLI uses the following syntax: ```shell-session consul-k8s -```` +``` ## Subcommands From 52f82f2831257369684bee947593b3e58b6f0882 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Sep 2021 16:07:56 -0700 Subject: [PATCH 18/18] adding timeout flags, wait flag, and updated build procedure --- website/content/docs/k8s/k8s-cli.mdx | 37 +++++++++++++++------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 221de10821..f996be9dfe 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -18,7 +18,7 @@ This topic describes the commands, subcommands, and available options for using 1. Navigate to the `consul-k8s/cli` directory and issue the following command to build the tool: ```shell-session - go build . + go build -o bin/consul-k8s ``` 1. (Optional) Move the binary to you `$PATH` for ease of use, e.g.: @@ -49,16 +49,18 @@ consul-k8s install 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 | -| `-config-file` | String 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. | 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:
`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 | -| `-set` | String value that enables you to set a customizeable value.
You can use the `-set` flag multiple times to set multiple values.
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.
You can use the `-set-file` flag multiple times to specify multiple files.
Consul Helm chart values are supported. | none | Optional | -| `-set-string` | String value that enables you to set a customizeable string value.
You can use the `-set-string` flag multiple times to specify multiple strings.
Consul Helm chart values are supported. | none | Optional | +| 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 | +| `-config-file` | String 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. | 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:
`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 | +| `-set` | String value that enables you to set a customizeable value.
You can use the `-set` flag multiple times to set multiple values.
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.
You can use the `-set-file` flag multiple times to specify multiple files.
Consul Helm chart values are supported. | none | Optional | +| `-set-string` | String value that enables you to set a customizeable string value.
You can use the `-set-string` flag multiple times to specify multiple strings.
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.
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` | 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. @@ -80,12 +82,13 @@ consul-k8s uninstall The following options are available. -| Flag | Description | Default | Required | -| --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------- | -| `-auto-approve`                                     | 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 | -| `-wipe-data` | Boolan 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 | +| Flag | Description | Default | Required | +| --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------- | +| `-auto-approve`                                     | 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.
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` | Optional | `10m` | +| `-wipe-data` | Boolan 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 | See [Global Options](#global-options) for additional commands that you can use when uninstalling Consul from Kubernetes.