whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Official 1.13 Release Docs (#11401)

Browse Source 
* Update metadata.generation behaviour for custom resources (#10705)

* update docs promoting plugins to beta (#10796)

* docs update to promote TaintBasedEvictions to beta (#10765)

* First Korean l10n work for dev-1.13 (#10719)

* Update outdated l10n(ko) contents (#10689)

fixes #10686

* Translate concepts/overview/what-is-kubernetes in Korean (#10690)

* Translate concepts/overview/what-is-kubernetes in Korean

* Feedback from ClaudiaJKang

* Translate concepts/overview/components in Korean (#10882)

* Translate concepts/overview/components in Korean #10717

* Translate concepts/overview/components in Korean

* Translate concepts/overview/components in Korean

* Apply Korean glossary: 서비스 어카운트

* Translate concepts/overview/kubernetes-api in Korean (#10773)

* Translate concepts/overview/kubernetes-api in Korean

* Applied feedback from ianychoi

* kubeadm: update the configuration docs to v1beta1 (#10959)

* kubeadm: add small v1beta1 related updates (#10988)

* ADD content/zh/docs/reference/setup-tools/kubeadm/kubeadm.md (#11031)

* ADD content/zh/docs/reference/setup-tools/kubeadm/kubeadm.md

* ADD content/zh/docs/reference/setup-tools/kubeadm/generated/kubeadm_init.md

* Update content/zh/docs/reference/setup-tools/kubeadm/kubeadm.md

Accepted

Co-Authored-By: YouthLab <tsui@highyouth.com>

* do not change 'master' or 'worker' nodes to '主从'

* Doc updates for volume scheduling GA (#10743)

* Doc updates for volume scheduling GA

* Make trivial change to kick build

* Document nodelease feature (#10699)

* advanced audit doc for ModeBlockingStrict (#10203)

* Rename EncryptionConfig to EncryptionConfiguration (#11080)

EncryptionConfig was renamed to EncryptedConfiguration and added to
the `apiserver.config.k8s.io` API group in Kubernetes 1.13.

The feature was previously in alpha and was not handling versions
properly, which lead to an originally unnoticed `v1` in the docs.

* content/zh/docs/reference/setup-tools/kubeadm/kubeadm-init.md

* trsanlate create-cluster-kubeadm.md to chinese (#11041)

* trsanlate create-cluster-kubeadm.md to chinese

* Update create-cluster-kubeadm.md

* update the feature stage in v1.13 (#11307)

* update new feature gates to document (#11295)

* refresh controller role list on rbac description page (#11290)

* node labeling restriction docs (#10944)

* Update 1.13 docs for CSI GA (#10893)

* dynamic audit documentation (#9947)

* adds dynamic audit documentation

* Copyedit for clarity

See also inline question/s

* Fix feature state shortcode

* Update feature state

* changes wording for dynamic audit flag behavior

* Minor copyedit

* fix dynamic audit yaml

* adds api enablement command to dynamic audit docs

* change ordering dynamic audit appears in

* add references to dynamic audit in webhook backend

* reword dynamic audit reference

* updates stages field for audit sink object

* changes audit sink api definition; rewords policy

* kubeadm: remove kube-proxy workaround (#11162)

* zh-trans content/en/docs/setup/independent/install-kubeadm.md (#11338)

* zh-trans content/en/docs/setup/independent/install-kubeadm.md

* Update install-kubeadm.md

* Update dry run feature to beta (#11140)

* vSphere volume raw block support doc update (#10932)

* Add docs for Windows DNS configurations (#10036)

* Update docs for fields allowed at root of CRD schema (#9973)

* Add docs for Windows DNS configurations

* add device monitoring documentation (#9945)

* kubeadm: adds upgrade instructions for 1.13 (#11138)

* kubeadm: adds upgrade instructions for 1.13

Signed-off-by: Chuck Ha <ha.chuck@gmail.com>

* add minor copyedits

Addressed a couple of copyedit comments a bit more cleanly.

* kubeadm: add improvements to HA docs (#11094)

* kubeadm: add information and diagrams for HA topologies

* kubeadm: update HA doc with simplified steps

* kubeadm: update HA doc with simplified steps

* edit ha, add new topology topic, reorder by weight

* troubleshoot markdown

* fix more markdown, fix links

* more markdown

* more markdown

* more markdown

* changes after reviewer comments

* add steps about Weave

* update note about stacked topology

* kubeadm external etcd HA upgrade 1.13 (#11364)

* kubeadm external etcd HA upgrade 1.13

Signed-off-by: Ruben Orduz <rubenoz@gmail.com>

* Update stacked controlplane steps

* kubeadm cert documentation (#11093)

* kubeadm certificate API and CSR documentation

* copyedits

* fix typo

* PR for diff docs (#10789)

* Empty commit against dev-1.13 for diff documentation

* Complete Declarative maangement with diff commands

* Second Korean l10n work for dev-1.13. (#11030)

* Update outdated l10n(ko) contents (#10915)
* Translate main menu for l10n(ko) docs (#10916)
* Translate tasks/run-application/horizontal-pod-autoscale-walkthrough (#10980)
* Translate content/ko/docs/concepts/overview/working-with-objects/kubernetes-object in Korean #11104 (#11332)
* Pick-right-solution page translates into Korean. (#11340)
* ko-trans: add jd/..., sap/..., ebay/..., homeoffice/... (#11336)
* Translate concept/workloads/pods/pod-overview.md (#11092)

Co-authored-by: June Yi <june.yi@samsung.com>
Co-authored-by: Jesang Myung <jesang.myung@gmail.com>
Co-authored-by: zerobig <38598117+zer0big@users.noreply.github.com>
Co-authored-by: Claudia J.Kang <claudiajkang@gmail.com>
Co-authored-by: lIuDuI <1693291525@qq.com>
Co-authored-by: Woojin Na(Eddie) <cheapluv@gmail.com>

* Rename encryption-at-rest related objects (#11059)

EncryptionConfig was renamed to EncryptedConfiguration and added to
the `apiserver.config.k8s.io` API group in Kubernetes 1.13.

The feature was previously in alpha and was not handling versions
properly, which lead to an originally unnoticed `v1` in the docs.

Also, the `--experimental-encryption-provider-config` flag is now called
just `--encryption-provider-config`.

* Documenting FlexVolume Resize alpha feature. (#10097)

* CR webhook conversion documentation (#10986)

* CR Conversion

* Addressing comments

* Addressing more comments

* Addressing even more comments

* Addressing even^2 more comments

* Remove references to etcd2 in v1.13 since support has been removed (#11414)

* Remove etcd2 references as etcd2 is deprecated

Link back to the v1.12 version of the etcd3 doc for
the etcd2->etcd3 migration instructions.

I updated the kube-apiserver reference manually,
unsure if that is auto-generated somehow.

The federation-apiserver can still potentially
support etcd2 so I didn't touch that.

* Remove outdated {master,node}.yaml files

There are master/node yaml files that reference
etcd2.service that are likely highly out of date.
I couldn't find any docs that actually reference
these templates so I removed them

* Address review comments

* Final Korean l10n work for dev-1.13 (#11440)

* Update outdated l10n(ko) contents (#11425)

fixes #11424

* Remove references to etcd2 in content/ko (#11416)

* Resolve conflicts against master for /ko contents (#11438)

* Fix unopened caution shortcode

* kubeadm: update the reference docs for 1.13 (#10960)

* docs update to promote TaintBasedEvictions to beta (#10765)

* First Korean l10n work for dev-1.13 (#10719)

* Update outdated l10n(ko) contents (#10689)

fixes #10686

* Translate concepts/overview/what-is-kubernetes in Korean (#10690)

* Translate concepts/overview/what-is-kubernetes in Korean

* Feedback from ClaudiaJKang

* Translate concepts/overview/components in Korean (#10882)

* Translate concepts/overview/components in Korean #10717

* Translate concepts/overview/components in Korean

* Translate concepts/overview/components in Korean

* Apply Korean glossary: 서비스 어카운트

* Translate concepts/overview/kubernetes-api in Korean (#10773)

* Translate concepts/overview/kubernetes-api in Korean

* Applied feedback from ianychoi

* kubeadm: update the configuration docs to v1beta1 (#10959)

* kubeadm: add small v1beta1 related updates (#10988)

* update new feature gates to document (#11295)

* Update dry run feature to beta (#11140)

* kubeadm: add improvements to HA docs (#11094)

* kubeadm: add information and diagrams for HA topologies

* kubeadm: update HA doc with simplified steps

* kubeadm: update HA doc with simplified steps

* edit ha, add new topology topic, reorder by weight

* troubleshoot markdown

* fix more markdown, fix links

* more markdown

* more markdown

* more markdown

* changes after reviewer comments

* add steps about Weave

* update note about stacked topology

* kubeadm: update reference docs

- add section about working with phases under kubeadm-init.md
- update GA / beta status of features
- kubeadm alpha phase was moved to kubeadm init phase
- new commands were added under kubeadm alpha
- included new CoreDNS usage examples

* Generate components and tools reference

* Add generated federation API Reference (#11491)

* Add generated federation API Reference

* Add front matter to federation reference

* Remove whitespace from federation front matter

* Remove more whitespace from federation front matter

* Remove superfluous kubefed reference

* Add frontmatter to generated kubefed reference

* Fix kubefed reference page frontmatter

* Generate kubectl reference docs 1.13 (#11487)

* Generate kubectl reference docs 1.13

* Fix links in kubectl reference

* Add 1.13 API reference (#11489)

* Update config.toml (#11486)

* Update config.toml

Preparing for 1.13 release, updating the config.toml and dropping the 1.8 docs reference.

* update dot releases and docsbranch typo

* adding .Site. to Params.currentUrl (#11503)

see https://github.com/kubernetes/website/pull/11502 for context

* Add 1.13 Release notes (#11499)
This commit is contained in:
Jim Angel
2018-12-03 19:21:11 -06:00
committed by Kubernetes Prow Robot
parent b1dde5578c
commit 27b7b453a9
347 changed files with 69250 additions and 4447 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md
+20 -214
View File
@@ -201,223 +201,29 @@ If the majority of etcd members have permanently failed, the etcd cluster is con
## Upgrading and rolling back etcd clusters
### Important assumptions
As of Kubernetes v1.13.0, etcd2 is no longer supported as a storage backend for
new or existing Kubernetes clusters. The timeline for Kubernetes support for
etcd2 and etcd3 is as follows:
The upgrade procedure described in this document assumes that either:
- Kubernetes v1.0: etcd2 only
- Kubernetes v1.5.1: etcd3 support added, new clusters still default to etcd2
- Kubernetes v1.6.0: new clusters created with `kube-up.sh` default to etcd3,
and `kube-apiserver` defaults to etcd3
- Kubernetes v1.9.0: deprecation of etcd2 storage backend announced
- Kubernetes v1.13.0: etcd2 storage backend removed, `kube-apiserver` will
refuse to start with `--storage-backend=etcd2`, with the
message `etcd2 is no longer a supported storage backend`
1. The etcd cluster has only a single node.
2. The etcd cluster has multiple nodes.
Before upgrading a v1.12.x kube-apiserver using `--storage-backend=etcd2` to
v1.13.x, etcd v2 data MUST by migrated to the v3 storage backend, and
kube-apiserver invocations changed to use `--storage-backend=etcd3`.
In this case, the upgrade procedure requires shutting down the
etcd cluster. During the time the etcd cluster is shut down, the Kubernetes API Server will be read only.
The process for migrating from etcd2 to etcd3 is highly dependent on how the
etcd cluster was deployed and configured, as well as how the Kubernetes
cluster was deployed and configured. We recommend that you consult your cluster
provider's documentation to see if there is a predefined solution.
{{< warning >}}
Deviations from the assumptions are untested by continuous
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).
{{< /warning >}}
### Background
As of Kubernetes version 1.5.1, we are still using etcd from the 2.2.1 release with
the v2 API. Also, we have no pre-existing process for updating etcd, as we have
never updated etcd by either minor or major version.
Note that we need to migrate both the etcd versions that we are using (from 2.2.1
to at least 3.0.x) as well as the version of the etcd API that Kubernetes talks to. The etcd 3.0.x
binaries support both the v2 and v3 API.
This document describes how to do this migration. If you want to skip the
background and cut right to the procedure, see [Upgrade
Procedure](#upgrade-procedure).
### etcd upgrade requirements
There are requirements on how an etcd cluster upgrade can be performed. The primary considerations are:
- Upgrade between one minor release at a time
- Rollback supported through additional tooling
#### One minor release at a time
Upgrade only one minor release at a time. For example, we cannot upgrade directly from 2.1.x to 2.3.x.
Within patch releases it is possible to upgrade and downgrade between arbitrary versions. Starting a cluster for
any intermediate minor release, waiting until the cluster is healthy, and then
shutting down the cluster will perform the migration. For example, to upgrade from version 2.1.x to 2.3.y,
it is enough to start etcd in 2.2.z version, wait until it is healthy, stop it, and then start the
2.3.y version.
#### Rollback via additional tooling
Versions 3.0+ of etcd do not support general rollback. That is,
after migrating from M.N to M.N+1, there is no way to go back to M.N.
The etcd team has provided a [custom rollback tool](https://git.k8s.io/kubernetes/cluster/images/etcd/rollback)
but the rollback tool has these limitations:
* This custom rollback tool is not part of the etcd repo and does not receive the same
testing as the rest of etcd. We are testing it in a couple of end-to-end tests.
There is only community support here.
* The rollback can be done only from the 3.0.x version (that is using the v3 API) to the
2.2.1 version (that is using the v2 API).
* The tool only works if the data is stored in `application/json` format.
* Rollback doesn’t preserve resource versions of objects stored in etcd.
{{< warning >}}
If the data is not kept in `application/json` format (see [Upgrade
Procedure](#upgrade-procedure)), you will lose the option to roll back to etcd
2.2.
{{< /warning >}}
The last bullet means that any component or user that has some logic
depending on resource versions may require restart after etcd rollback. This
includes that all clients using the watch API, which depends on
resource versions. Since both the kubelet and kube-proxy use the watch API, a
rollback might require restarting all Kubernetes components on all nodes.
{{< note >}}
At the time of writing, both Kubelet and KubeProxy are using “resource
version” only for watching (i.e. are not using resource versions for anything
else). And both are using reflector and/or informer frameworks for watching
(i.e. they don’t send watch requests themselves). Both those frameworks if they
can’t renew watch, they will start from “current version” by doing “list + watch
from the resource version returned by list”. That means that if the apiserver
will be down for the period of rollback, all of node components should basically
restart their watches and start from “now” when apiserver is back. And it will
be back with new resource version. That would mean that restarting node
components is not needed. But the assumptions here may not hold forever.
{{< /note >}}
{{% /capture %}}
{{% capture discussion %}}
### Design
This section describes how we are going to do the migration, given the
[etcd upgrade requirements](#etcd-upgrade-requirements).
Note that because the code changes in Kubernetes code needed
to support the etcd v3 API are local and straightforward, we do not
focus on them at all. We focus only on the upgrade/rollback here.
### New etcd Docker image
We decided to completely change the content of the etcd image and the way it works.
So far, the Docker image for etcd in version X has contained only the etcd and
etcdctl binaries.
Going forward, the Docker image for etcd in version X will contain multiple
versions of etcd. For example, the 3.0.17 image will contain the 2.2.1, 2.3.7, and
3.0.17 binaries of etcd and etcdctl. This will allow running etcd in multiple
different versions using the same Docker image.
Additionally, the image will contain a custom script, written by the Kubernetes team,
for doing migration between versions. The image will also contain the rollback tool
provided by the etcd team.
### Migration script
The migration script that will be part of the etcd Docker image is a bash
script that works as follows:
1. Detect which version of etcd we were previously running.
For that purpose, we have added a dedicated file, `version.txt`, that
holds that information and is stored in the etcd-data-specific directory,
next to the etcd data. If the file doesn’t exist, we default it to version 2.2.1.
1. If we are in version 2.2.1 and are supposed to upgrade, backup
data.
1. Based on the detected previous etcd version and the desired one
(communicated via environment variable), do the upgrade steps as
needed. This means that for every minor etcd release greater than the detected one and
less than or equal to the desired one:
1. Start etcd in that version.
1. Wait until it is healthy. Healthy means that you can write some data to it.
1. Stop this etcd. Note that this etcd will not listen on the default
etcd port. It is hard coded to listen on ports that the API server is not
configured to connect to, which means that API server won’t be able to connect
to it. Assuming no other client goes out of its way to try to
connect and write to this obscure port, no new data will be written during
this period.
1. If the desired API version is v3 and the detected version is v2, do the offline
migration from the v2 to v3 data format. For that we use two tools:
* ./etcdctl migrate: This is the official tool for migration provided by the etcd team.
* A custom script that is attaching TTLs to events in the etcd. Note that etcdctl
migrate doesn’t support TTLs.
1. After every successful step, update contents of the version file.
This will protect us from the situation where something crashes in the
meantime ,and the version file gets completely unsynchronized with the
real data. Note that it is safe if the script crashes after the step is
done and before the file is updated. This will only result in redoing one
step in the next try.
All the previous steps are for the case where the detected version is less than or
equal to the desired version. In the opposite case, that is for a rollback, the
script works as follows:
1. Verify that the detected version is 3.0.x with the v3 API, and the
desired version is 2.2.1 with the v2 API. We don’t support any other rollback.
1. If so, we run the custom tool provided by etcd team to do the offline
rollback. This tool reads the v3 formatted data and writes it back to disk
in v2 format.
1. Finally update the contents of the version file.
### 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
desired version, this will be no-op.
1. Start etcd in the desired version.
Starting in Kubernetes version 1.6, this has been done in the manifests for new
Google Compute Engine clusters. You should also specify these environment
variables. In particular, you must keep `STORAGE_MEDIA_TYPE` set to
`application/json` if you wish to preserve the option to roll back.
```
TARGET_STORAGE=etcd3
ETCD_IMAGE=3.0.17
TARGET_VERSION=3.0.17
STORAGE_MEDIA_TYPE=application/json
```
To roll back, use these:
```
TARGET_STORAGE=etcd2
ETCD_IMAGE=3.0.17
TARGET_VERSION=2.2.1
STORAGE_MEDIA_TYPE=application/json
```
{{< note >}}
This procedure upgrades from 2.x to 3.x. Version `3.0.17` is not recommended for running in production (see [prerequisites](#prerequisites) for minimum recommended etcd versions).
{{< /note >}}
## 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/{{< param "githubbranch" >}}/cluster/gce/manifests/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 -X PUT "http://${host}:${port}/v2/keys/_test"
```
If your cluster was created via `kube-up.sh` and is still using etcd2 as its
storage backend, please consult the [Kubernetes v1.12 etcd cluster upgrade docs](https://v1-12.docs.kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/#upgrading-and-rolling-back-etcd-clusters)
{{% /capture %}}