Reorg helm chart docs #6849

lkysow · 2019-11-28T21:27:25Z

Remove duplicate install instructions from the Helm Chart page and
kept them in Running Consul
Renamed Helm Chart to Helm Chart Reference because that's mostly what
it contains (along with some examples)
Renamed Running Consul to Installing Consul
Changed instructions to be for installing using Helm 3 and added
notes if using Helm 2
Used release name "hashicorp" so subsequent instructions can be more
concise and pastable, e.g. "port forward to svc/hashicorp-consul-server" vs. "port
forward to svc/-consul-server"
Use config.yaml as the name for the override values file since it
differentiates from the default values.yaml file and its the name of the
file used in the helm docs
(https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing)

lkysow · 2019-11-28T21:30:12Z

website/source/docs/platform/k8s/index.html.md

@@ -63,17 +65,7 @@ There are several ways to try Consul with Kubernetes in different environments.
 - The [Consul and Kubernetes Deployment](
   https://learn.hashicorp.com/consul/day-1-operations/kubernetes-deployment-guide?utm_source=consul.io&utm_medium=docs) guide covers the necessary steps to install and configure a new Consul cluster on Kubernetes in production.

-## "consul-k8s" Project


Since this documentation doesn't seem important to users I thought it best to remove it. Especially from the index page.

How do we know it's not important to users?

My thinking is that most users will install the helm chart and use the values.yaml to configure their installation. So when they first come to this page, they don't need to know about the consul-k8s repo.

lkysow · 2019-11-28T21:30:55Z

website/source/docs/platform/k8s/run.html.md

@@ -1,12 +1,12 @@
 ---
 layout: "docs"
-page_title: "Running Consul - Kubernetes"
+page_title: "Installing Consul on Kubernetes - Kubernetes"


I felt Installing was better than Running since that's what I'd click on looking for installation instructions. We use Installing Consul in the top level docs as well.

lkysow · 2019-11-28T21:31:35Z

website/source/docs/platform/k8s/run.html.md


-# Checkout a tagged version
-$ git checkout v0.1.0
+```bash


I moved these instructions over from the helm.html page. I think they're a bit cleaner

lkysow · 2019-11-28T21:32:00Z

website/source/docs/platform/k8s/run.html.md

+`helm upgrade`. See the [Upgrading Consul on Kubernetes](/docs/platform/k8s/run.html#upgrading-consul-on-kubernetes)
+section for more details.
+
+## Uninstalling Consul


I've added these instructions here.

ishustava

Thanks for doing the work of reviewing and reorganizing the docs 🥇 💯 I left some comments. Overall it looks good to me. Other than small improvements, the one important thing to me is to keep the security warning that got removed.

ishustava · 2019-12-03T18:03:17Z

website/source/docs/platform/k8s/index.html.md

@@ -63,17 +65,7 @@ There are several ways to try Consul with Kubernetes in different environments.
 - The [Consul and Kubernetes Deployment](
   https://learn.hashicorp.com/consul/day-1-operations/kubernetes-deployment-guide?utm_source=consul.io&utm_medium=docs) guide covers the necessary steps to install and configure a new Consul cluster on Kubernetes in production.

-## "consul-k8s" Project


How do we know it's not important to users?

ishustava · 2019-12-03T18:06:59Z

website/source/docs/platform/k8s/run.html.md

@@ -17,14 +17,17 @@ 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/platform/k8s/run.html#architecture) section. If you would like to get hands-on experience testing Consul on Kubernetes, try the step-by-step beginner tutorial with an accompanying video in the [Minikube with Consul guide](https://learn.hashicorp.com/consul/getting-started-k8s/minikube?utm_source=consul.io&utm_medium=docs)

-## Helm Chart
+## Helm Chart Installation

 The recommended way to run Consul on Kubernetes is via the
 [Helm chart](/docs/platform/k8s/helm.html). 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 seconds.


Not related to your change, but since I'm reading it, should this say "in minutes"? I feel like installing it in seconds is a bit of stretch.

Seconds >60? 😆 I'll change it to a couple minutes

ishustava · 2019-12-03T18:09:58Z

website/source/docs/platform/k8s/run.html.md

-# Clone the chart repo
-$ git clone https://github.com/hashicorp/consul-helm.git
-$ cd consul-helm
+Clone the chart at that version, for example if the latest version is


Suggested change

Clone the chart at that version, for example if the latest version is

Clone the chart at that version, for example, if the latest version is

ishustava · 2019-12-03T18:15:06Z

website/source/docs/platform/k8s/run.html.md

+```sh
+$ helm install hashicorp ./consul-helm
+NAME: hashicorp
 ...


It'd be nice to say here explicitly that these instructions are for Helm 3. I feel like Helm 3 hasn't become the de facto standard yet and people are still transitioning to it.

ishustava · 2019-12-03T18:16:19Z

website/source/docs/platform/k8s/run.html.md

+`helm upgrade`. See the [Upgrading Consul on Kubernetes](/docs/platform/k8s/run.html#upgrading-consul-on-kubernetes)
+section for more details.
+
+## Uninstalling Consul


ishustava · 2019-12-03T18:17:58Z

website/source/docs/platform/k8s/run.html.md

+
+-> If using Helm 2, run `helm delete --purge hashicorp`
+
+After deleting the Helm release, you need to delete the PersistentVolumeClaims


Suggested change

After deleting the Helm release, you need to delete the PersistentVolumeClaims

After deleting the Helm release, you need to delete the `PersistentVolumeClaims`

ishustava · 2019-12-03T18:18:47Z

website/source/docs/platform/k8s/run.html.md

+-> If using Helm 2, run `helm delete --purge hashicorp`
+
+After deleting the Helm release, you need to delete the PersistentVolumeClaims
+that store Consul's data. These are not deleted by Helm due to a [bug](https://github.com/helm/helm/issues/5156).


Kind of nitpicking here, but technically pvcs don't store data.

Suggested change

that store Consul's data. These are not deleted by Helm due to a [bug](https://github.com/helm/helm/issues/5156).

for persistent volumes that store Consul's data. These are not deleted by Helm due to a [bug](https://github.com/helm/helm/issues/5156).

ishustava · 2019-12-03T18:24:01Z

website/source/docs/platform/k8s/run.html.md

-For security reasons, it isn't exposed via a Service by default so you must
-use `kubectl port-forward` to visit the UI. Once the port is forwarded as
-shown below, navigate your browser to `http://localhost:8500`.
+For security reasons, it isn't exposed via a LoadBalancer Service by default so you must


Suggested change

For security reasons, it isn't exposed via a LoadBalancer Service by default so you must

For security reasons, it isn't exposed via a `LoadBalancer` Service by default so you must

ishustava · 2019-12-03T18:26:24Z

website/source/docs/platform/k8s/run.html.md

-The UI can also be exposed via a Kubernetes Service. To do this, configure
-the [`ui.service` chart values](/docs/platform/k8s/helm.html#v-ui-service).


I think this comment is still valuable if we change the wording to say LoadBalancer service rather than "Kubernetes Service". Did you think it's redundant?

If they're not using ACLs then they're exposing the Consul HTTP API to the world and even with ACLs the anonymous token lets you read all nodes and services. So I thought it best not to encourage it.

Not necessarily, this depends on the security groups and whether they use an internal or an external load balancer. Currently, we allow setting annotations for the UI service, and on AWS, for example, you can create an internal load balancer with an annotation.

Okay I'll add it back.

website/source/docs/platform/k8s/helm.html.md

codecov · 2019-12-03T19:50:05Z

Codecov Report

❗ No coverage uploaded for pull request base (master@eda868a). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #6849   +/-   ##
=========================================
  Coverage          ?   65.79%           
=========================================
  Files             ?      435           
  Lines             ?    52398           
  Branches          ?        0           
=========================================
  Hits              ?    34473           
  Misses            ?    13792           
  Partials          ?     4133

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update eda868a...5412ba9. Read the comment docs.

ishustava

👍 😀

- Remove duplicate install instructions from the Helm Chart page and kept them in Running Consul - Renamed Helm Chart to Helm Chart Reference because that's mostly what it contains (along with some examples) - Renamed Running Consul to Installing Consul - Changed instructions to be for installing using Helm 3 and added notes if using Helm 2 - Used release name "hashicorp" so subsequent instructions can be more concise and pastable, e.g. "port forward to svc/hashicorp-consul-server" vs. "port forward to svc/<your release name>-consul-server" - Use config.yaml as the name for the override values file since it differentiates from the default values.yaml file and its the name of the file used in the helm docs (https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing)

ghost · 2020-01-25T02:03:06Z

Hey there,

This issue has been automatically locked because it is closed and there hasn't been any activity for at least 30 days.

If you are still experiencing problems, or still have questions, feel free to open a new one 👍.

lkysow force-pushed the helm-chart-docs branch from 875eb78 to 9f9b5a5 Compare November 28, 2019 21:28

lkysow requested a review from a team November 28, 2019 21:29

lkysow commented Nov 28, 2019

View reviewed changes

ishustava reviewed Dec 3, 2019

View reviewed changes

lkysow force-pushed the helm-chart-docs branch 3 times, most recently from 47b3b7f to ad85663 Compare December 3, 2019 19:34

ishustava approved these changes Dec 4, 2019

View reviewed changes

lkysow force-pushed the helm-chart-docs branch from ad85663 to 5412ba9 Compare December 4, 2019 01:49

lkysow merged commit 7ac6a08 into master Dec 4, 2019

lkysow deleted the helm-chart-docs branch December 4, 2019 01:49

ghost locked and limited conversation to collaborators Jan 25, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorg helm chart docs #6849

Reorg helm chart docs #6849

lkysow commented Nov 28, 2019 •

edited

Loading

lkysow Nov 28, 2019

ishustava Dec 3, 2019

lkysow Dec 3, 2019

lkysow Nov 28, 2019

lkysow Nov 28, 2019

lkysow Nov 28, 2019

ishustava Dec 3, 2019

ishustava left a comment

ishustava Dec 3, 2019

ishustava Dec 3, 2019

lkysow Dec 3, 2019

ishustava Dec 3, 2019

ishustava Dec 3, 2019

lkysow Dec 3, 2019

ishustava Dec 3, 2019

ishustava Dec 3, 2019

ishustava Dec 3, 2019

ishustava Dec 3, 2019

ishustava Dec 3, 2019 •

edited

Loading

lkysow Dec 3, 2019

ishustava Dec 3, 2019

lkysow Dec 3, 2019

codecov bot commented Dec 3, 2019 •

edited

Loading

ishustava left a comment

ghost commented Jan 25, 2020

	Clone the chart at that version, for example if the latest version is
	Clone the chart at that version, for example, if the latest version is


		-> If using Helm 2, run `helm delete --purge hashicorp`

		After deleting the Helm release, you need to delete the PersistentVolumeClaims

	that store Consul's data. These are not deleted by Helm due to a [bug](https://github.com/helm/helm/issues/5156).
	for 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 security reasons, it isn't exposed via a LoadBalancer Service by default so you must
	For security reasons, it isn't exposed via a `LoadBalancer` Service by default so you must

		The UI can also be exposed via a Kubernetes Service. To do this, configure
		the [`ui.service` chart values](/docs/platform/k8s/helm.html#v-ui-service).

Reorg helm chart docs #6849

Reorg helm chart docs #6849

Conversation

lkysow commented Nov 28, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ishustava left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ishustava Dec 3, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Dec 3, 2019 • edited Loading

Codecov Report

ishustava left a comment

Choose a reason for hiding this comment

ghost commented Jan 25, 2020

lkysow commented Nov 28, 2019 •

edited

Loading

ishustava Dec 3, 2019 •

edited

Loading

codecov bot commented Dec 3, 2019 •

edited

Loading