From 697e0d3574c9abbb58f81f9d5dd5c6141c46cb8d Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Sat, 13 May 2017 20:54:58 -0700 Subject: [PATCH] Move and consolidate etcd topics. (#3739) --- _data/concepts.yml | 2 - _data/tasks.yml | 1 + .../cluster-administration/configure-etcd.md | 53 ------------------- .../configure-upgrade-etcd.md} | 49 +++++++++++++---- 4 files changed, 41 insertions(+), 64 deletions(-) delete mode 100644 docs/concepts/cluster-administration/configure-etcd.md rename docs/{concepts/cluster-administration/etcd-upgrade.md => tasks/administer-cluster/configure-upgrade-etcd.md} (86%) diff --git a/_data/concepts.yml b/_data/concepts.yml index 2cab7cd54a..cc6ca1996a 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -49,8 +49,6 @@ toc: - title: Cluster Administration section: - docs/concepts/cluster-administration/cluster-administration-overview.md - - docs/concepts/cluster-administration/configure-etcd.md - - docs/concepts/cluster-administration/etcd-upgrade.md - docs/concepts/cluster-administration/manage-deployment.md - docs/concepts/cluster-administration/networking.md - docs/concepts/cluster-administration/network-plugins.md diff --git a/_data/tasks.yml b/_data/tasks.yml index 69813aaaa7..629ad24aa4 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -94,6 +94,7 @@ toc: - title: Administering a Cluster section: + - docs/tasks/administer-cluster/configure-upgrade-etcd.md - docs/tasks/administer-cluster/apply-resource-quota-limit.md - docs/tasks/administer-cluster/out-of-resource.md - docs/tasks/administer-cluster/cpu-memory-limit.md diff --git a/docs/concepts/cluster-administration/configure-etcd.md b/docs/concepts/cluster-administration/configure-etcd.md deleted file mode 100644 index 7a5db57110..0000000000 --- a/docs/concepts/cluster-administration/configure-etcd.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Configuring Kubernetes Use of etcd -redirect_from: -- "/docs/concepts/storage/etcd-store-api-object/" -- "/docs/concepts/storage/etcd-store-api-object.html" -redirect_from: -- "/docs/admin/etcd/" -- "/docs/admin/etcd.html" ---- - -[etcd](https://coreos.com/etcd/docs/latest/) is a highly-available key value -store which Kubernetes uses for persistent storage of all of its REST API -objects. - -## Configuration: high-level goals - -Access Control: give *only* kube-apiserver read/write access to etcd. You do not -want apiserver's etcd exposed to every node in your cluster (or worse, to the -internet at large), because access to etcd is equivalent to root in your -cluster. - -Data Reliability: for reasonable safety, either etcd needs to be run as a -[cluster](/docs/admin/high-availability/#clustering-etcd) (multiple machines each running -etcd) or etcd's data directory should be located on durable storage (e.g., GCE's -persistent disk). In either case, if high availability is required--as it might -be in a production cluster--the data directory ought to be [backed up -periodically](https://coreos.com/etcd/docs/latest/op-guide/recovery.html), -to reduce downtime in case of corruption. - -## Default configuration - -The default setup scripts use kubelet's file-based static pods feature to run etcd in a -[pod](http://releases.k8s.io/{{page.githubbranch}}/cluster/saltbase/salt/etcd/etcd.manifest). This manifest should only -be run on master VMs. The default location that kubelet scans for manifests is -`/etc/kubernetes/manifests/`. - -## Kubernetes's usage of etcd - -By default, Kubernetes objects are stored under the `/registry` key in etcd. -This path can be prefixed by using the [kube-apiserver](/docs/admin/kube-apiserver) flag -`--etcd-prefix="/foo"`. - -`etcd` is the only place that Kubernetes keeps state. - -## Troubleshooting - -To test whether `etcd` is running correctly, you can try writing a value to a -test key. On your master VM (or somewhere with firewalls configured such that -you can talk to your cluster's etcd), try: - -```shell -curl -fs -X PUT "http://${host}:${port}/v2/keys/_test" -``` diff --git a/docs/concepts/cluster-administration/etcd-upgrade.md b/docs/tasks/administer-cluster/configure-upgrade-etcd.md similarity index 86% rename from docs/concepts/cluster-administration/etcd-upgrade.md rename to docs/tasks/administer-cluster/configure-upgrade-etcd.md index 3df9190d1e..67bbaa924a 100644 --- a/docs/concepts/cluster-administration/etcd-upgrade.md +++ b/docs/tasks/administer-cluster/configure-upgrade-etcd.md @@ -1,17 +1,22 @@ --- -assignees: - mml - wojtek-t -title: Upgrading and Rolling Back etcd +title: Configuring, Upgrading, and Rolling Back etcd redirect_from: +- "/docs/concepts/storage/etcd-store-api-object/" +- "/docs/concepts/storage/etcd-store-api-object.html" +- "/docs/admin/etcd/" +- "/docs/admin/etcd.html" - "/docs/admin/etcd_upgrade/" - "/docs/admin/etcd_upgrade.html" +- "/docs/concepts/cluster-administration/configure-etcd/" +- "/docs/concepts/cluster-administration/configure-etcd.html" +- "/docs/concepts/cluster-administration/etcd-upgrade/" +- "/docs/concepts/cluster-administration/etcd-upgrade.html" --- -## About etcd - [etcd](https://coreos.com/etcd/docs/latest/) is a highly-available key value -store, which Kubernetes uses for persistent storage of all of its REST API +store which Kubernetes uses for persistent storage of all of its REST API objects. -### Important assumptions +## Important assumptions The upgrade procedure described in this document assumes that either: @@ -35,7 +40,7 @@ integration, and deviations might create undesirable consequences. Additional information about operating an etcd cluster is available [from the etcd maintainers](https://github.com/coreos/etcd/tree/master/Documentation). -### etcd for Kubernetes: high-level goals +## etcd for Kubernetes: high-level goals Access control: Give only kube-apiserver read/write access to etcd. You do not want the API server's etcd exposed to every node in your cluster, or worse, to the @@ -118,7 +123,7 @@ restart their watches and start from “now” when apiserver is back. And it wi be back with new resource version. That would mean that restarting node components is not needed. But the assumptions here may not hold forever. -## Design +### Design This section describes how we are going to do the migration, given the [etcd upgrade requirements](#etcd-upgrade-requirements). @@ -187,7 +192,7 @@ script works as follows: in v2 format. 1. Finally update the contents of the version file. -### Upgrade procedure +## Upgrade procedure Simply modify the command line in the etcd manifest to: 1. Run the migration script. If the previously run version is already in the @@ -215,3 +220,29 @@ TARGET_VERSION=2.2.1 STORAGE_MEDIA_TYPE=application/json ``` +## Notes for etcd Version 2.2.1 + +### Default configuration + +The default setup scripts use kubelet's file-based static pods feature to run etcd in a +[pod](http://releases.k8s.io/{{page.githubbranch}}/cluster/saltbase/salt/etcd/etcd.manifest). This manifest should only +be run on master VMs. The default location that kubelet scans for manifests is +`/etc/kubernetes/manifests/`. + +### Kubernetes's usage of etcd + +By default, Kubernetes objects are stored under the `/registry` key in etcd. +This path can be prefixed by using the [kube-apiserver](/docs/admin/kube-apiserver) flag +`--etcd-prefix="/foo"`. + +`etcd` is the only place that Kubernetes keeps state. + +### Troubleshooting + +To test whether `etcd` is running correctly, you can try writing a value to a +test key. On your master VM (or somewhere with firewalls configured such that +you can talk to your cluster's etcd), try: + +```shell +curl -fs -X PUT "http://${host}:${port}/v2/keys/_test" +```