From 320fcf4510963c29f12036c7de782d0ca7144319 Mon Sep 17 00:00:00 2001 From: Luke Kysow <1034429+lkysow@users.noreply.github.com> Date: Fri, 29 Jan 2021 11:15:40 -0800 Subject: [PATCH] Add operations section to k8s notes (#9625) * Add operations section to k8s notes * Unify faq/troubleshooting --- .../tls-on-existing-cluster.mdx | 0 .../content/docs/k8s/operations/uninstall.mdx | 96 +++++++++++++++++++ website/content/docs/k8s/uninstall.mdx | 34 ------- website/content/docs/troubleshoot/faq.mdx | 41 +++++--- website/data/docs-navigation.js | 21 +++- website/redirects.next.js | 10 ++ 6 files changed, 154 insertions(+), 48 deletions(-) rename website/content/docs/k8s/{ => operations}/tls-on-existing-cluster.mdx (100%) create mode 100644 website/content/docs/k8s/operations/uninstall.mdx delete mode 100644 website/content/docs/k8s/uninstall.mdx diff --git a/website/content/docs/k8s/tls-on-existing-cluster.mdx b/website/content/docs/k8s/operations/tls-on-existing-cluster.mdx similarity index 100% rename from website/content/docs/k8s/tls-on-existing-cluster.mdx rename to website/content/docs/k8s/operations/tls-on-existing-cluster.mdx diff --git a/website/content/docs/k8s/operations/uninstall.mdx b/website/content/docs/k8s/operations/uninstall.mdx new file mode 100644 index 000000000..777433103 --- /dev/null +++ b/website/content/docs/k8s/operations/uninstall.mdx @@ -0,0 +1,96 @@ +--- +layout: docs +page_title: Uninstall +sidebar_title: Uninstall +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. + +1. First, run `helm delete`: + + ```shell-session + $ helm delete hashicorp + release "hashicorp" uninstalled + ``` + + -> If using Helm 2, run `helm delete --purge hashicorp` + +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: + + ```shell-session + $ kubectl get pvc -l chart=consul-helm + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + data-default-hashicorp-consul-server-0 Bound pvc-32cb296b-1213-11ea-b6f0-42010a8001db 10Gi RWO standard 17m + data-default-hashicorp-consul-server-1 Bound pvc-32d79919-1213-11ea-b6f0-42010a8001db 10Gi RWO standard 17m + data-default-hashicorp-consul-server-2 Bound pvc-331581ea-1213-11ea-b6f0-42010a8001db 10Gi RWO standard 17m + + $ kubectl delete pvc -l chart=consul-helm + persistentvolumeclaim "data-default-hashicorp-consul-server-0" deleted + persistentvolumeclaim "data-default-hashicorp-consul-server-1" deleted + persistentvolumeclaim "data-default-hashicorp-consul-server-2" deleted + ``` + + ~> **NOTE:** This will delete **all** data stored in Consul and it can't be + recovered unless you've taken other backups. + +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 +``` + +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`. + +```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: + + ```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: + + ```shell-session + $ kubectl get serviceaccount consul-tls-init + NAME SECRETS AGE + consul-tls-init 1 47m + ``` + + ```shell-session + $ kubectl delete serviceaccount consul-tls-init + serviceaccount "consul-tls-init" deleted + ``` diff --git a/website/content/docs/k8s/uninstall.mdx b/website/content/docs/k8s/uninstall.mdx deleted file mode 100644 index a61527d44..000000000 --- a/website/content/docs/k8s/uninstall.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: docs -page_title: Uninstall -sidebar_title: Uninstall -description: Uninstall Consul on Kubernetes ---- - -# Uninstall Consul - -Consul can be uninstalled via the `helm delete` command: - -```shell-session -$ helm delete hashicorp -release "hashicorp" uninstalled -``` - --> If using Helm 2, run `helm delete --purge hashicorp` - -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: - -```shell-session -$ kubectl get pvc -l chart=consul-helm -NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE -data-default-hashicorp-consul-server-0 Bound pvc-32cb296b-1213-11ea-b6f0-42010a8001db 10Gi RWO standard 17m -data-default-hashicorp-consul-server-1 Bound pvc-32d79919-1213-11ea-b6f0-42010a8001db 10Gi RWO standard 17m -data-default-hashicorp-consul-server-2 Bound pvc-331581ea-1213-11ea-b6f0-42010a8001db 10Gi RWO standard 17m - -$ kubectl delete pvc -l chart=consul-helm -persistentvolumeclaim "data-default-hashicorp-consul-server-0" deleted -persistentvolumeclaim "data-default-hashicorp-consul-server-1" deleted -persistentvolumeclaim "data-default-hashicorp-consul-server-2" deleted -``` diff --git a/website/content/docs/troubleshoot/faq.mdx b/website/content/docs/troubleshoot/faq.mdx index 1b4c383d2..ad2339f5f 100644 --- a/website/content/docs/troubleshoot/faq.mdx +++ b/website/content/docs/troubleshoot/faq.mdx @@ -6,7 +6,24 @@ sidebar_title: FAQ # Frequently Asked Questions -## Q: What is Checkpoint? / Does Consul call home? +## Consul on Kubernetes + +### Q: Can I upgrade directly to a specific Helm chart version or should I upgrade one patch release at a time? + +It is safe to upgrade directly to a specific version. Be sure to read the release notes for all versions you're upgrading +through and look for any breaking changes. + +### Q: Can I upgrade in place or should I spin up a new Kubernetes cluster? + +It is always safer to spin up a new Kubernetes cluster but that is not an +option for most teams. Consul supports [upgrading in place](/docs/k8s/upgrade). + +Non-production environments should be upgraded first. If upgrading +a Consul version, Consul data should be [backed up](https://learn.hashicorp.com/tutorials/consul/kubernetes-disaster-recovery). + +## Generic Consul Questions + +### Q: What is Checkpoint? / Does Consul call home? Consul makes use of a HashiCorp service called [Checkpoint](http://checkpoint.hashicorp.com) which is used to check for updates and critical security bulletins. @@ -19,14 +36,14 @@ optional and can be disabled. See [`disable_anonymous_signature`](/docs/agent/options#disable_anonymous_signature) and [`disable_update_check`](/docs/agent/options#disable_update_check). -## Q: Does Consul rely on UDP Broadcast or Multicast? +### Q: Does Consul rely on UDP Broadcast or Multicast? Consul uses the [Serf](https://www.serf.io) gossip protocol which relies on TCP and UDP unicast. Broadcast and Multicast are rarely available in a multi-tenant or cloud network environment. For that reason, Consul and Serf were both designed to avoid any dependence on those capabilities. -## Q: Is Consul eventually or strongly consistent? +### Q: Is Consul eventually or strongly consistent? Consul has two important subsystems, the service catalog and the gossip protocol. @@ -46,7 +63,7 @@ the catalog may come via the gossip protocol which is eventually consistent meaning the current state of the catalog can lag behind until the state is reconciled. -## Q: Are _failed_ or _left_ nodes ever removed? +### Q: Are _failed_ or _left_ nodes ever removed? To prevent an accumulation of dead nodes (nodes in either _failed_ or _left_ states), Consul will automatically remove dead nodes out of the catalog. This @@ -57,7 +74,7 @@ reasons to trim the number of _failed_ or _left_ nodes is not advised (nodes in the _failed_ or _left_ state do not cause any additional burden on Consul). -## Q: Does Consul support delta updates for watchers or blocking queries? +### Q: Does Consul support delta updates for watchers or blocking queries? Consul does not currently support sending a delta or a change only response to a watcher or a blocking query. The API simply allows for an edge-trigger @@ -68,12 +85,12 @@ By design, Consul offloads this to clients instead of attempting to support the delta calculation. This avoids expensive state maintenance on the servers as well as race conditions between data updates and watch registrations. -## Q: What network ports does Consul use? +### Q: What network ports does Consul use? The [Ports Used](/docs/agent/options#ports) section of the Configuration documentation lists all ports that Consul uses. -## Q: Does Consul require certain user process resource limits? +### Q: Does Consul require certain user process resource limits? There should be only a small number of open file descriptors required for a Consul client agent. The gossip layers perform transient connections with @@ -92,7 +109,7 @@ The default ulimits are usually sufficient for Consul, but you should closely scrutinize your own environment's specific needs and identify the root cause of any excessive resource utilization before arbitrarily increasing the limits. -## Q: What is the per-key value size limitation for Consul's key/value store? +### Q: What is the per-key value size limitation for Consul's key/value store? The limit on a key's value size is 512KB. This is strictly enforced and an HTTP 413 status will be returned to any client that attempts to store more @@ -100,7 +117,7 @@ than that limit in a value. It should be noted that the Consul key/value store is not designed to be used as a general purpose database. See [Server Performance](/docs/install/performance) for more details. -## Q: What data is replicated between Consul datacenters? +### Q: What data is replicated between Consul datacenters? In general, data is not replicated between different Consul datacenters. When a request is made for a resource in another datacenter, the local Consul servers @@ -114,7 +131,7 @@ can be replicated, such as with Consul's built-in capability, or external tools like [consul-replicate](https://github.com/hashicorp/consul-replicate). -## Q: Can Consul natively handle protecting against other processes accessing Consul's memory state? +### Q: Can Consul natively handle protecting against other processes accessing Consul's memory state? Consul does not provide built-in memory access protections, and doesn't interact with the host system to change or manipulate @@ -127,7 +144,7 @@ normally do for individual processes, based on your operating system. Please see our [Security Model](/docs/internals/security) for more information. -## Q: Are the Consul Docker Images OCI Compliant? +### Q: Are the Consul Docker Images OCI Compliant? The official [Consul Docker image](https://hub.docker.com/_/consul/) uses [Docker image schema](https://docs.docker.com/registry/spec/manifest-v2-2/) V2, @@ -136,7 +153,7 @@ command `docker manifest inspect consul` to inspect the manifest payload. The `docker manifest inspect` may require you to enable experimental features to use. -## What browsers are supported by the Consul UI? +### Q: What browsers are supported by the Consul UI? Consul currently supports all 'evergreen' browsers, as they are generally on up-to-date versions. This means we support: diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index a28affc2b..aa62884b1 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -170,7 +170,6 @@ export default [ }, ], }, - 'tls-on-existing-cluster', { category: 'connect', content: [ @@ -191,7 +190,25 @@ export default [ category: 'upgrade', content: ['compatibility'], }, - 'uninstall', + { + category: 'operations', + name: 'Operations', + content: ['uninstall', 'tls-on-existing-cluster'], + }, + { + name: 'Troubleshoot', + content: [ + { + title: 'Common Error Messages', + href: + '/docs/troubleshoot/common-errors#common-errors-on-kubernetes', + }, + { + title: 'FAQ', + href: '/docs/troubleshoot/faq#consul-on-kubernetes', + }, + ], + }, 'helm', ], }, diff --git a/website/redirects.next.js b/website/redirects.next.js index 10ff5de2e..cffeb7d46 100644 --- a/website/redirects.next.js +++ b/website/redirects.next.js @@ -1215,4 +1215,14 @@ module.exports = [ // disallow '.html' or '/index.html' in favor of cleaner, simpler paths { source: '/:path*/index', destination: '/:path*', permanent: true }, { source: '/:path*.html', destination: '/:path*', permanent: true }, + { + source: '/docs/k8s/uninstall', + destination: '/docs/k8s/operations/uninstall', + permanent: true, + }, + { + source: '/docs/k8s/tls-on-existing-cluster', + destination: '/docs/k8s/operations/tls-on-existing-cluster', + permanent: true, + }, ]