From 7865afe45928f1c528bbb8ddf50e4d6bacf1d50f Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Tue, 24 Oct 2017 11:29:58 +0800 Subject: [PATCH 01/53] Migrate dynamic provisioning documentation --- _data/concepts.yml | 3 +- docs/concepts/storage/dynamic-provisioning.md | 124 ++++++++++++++++++ 2 files changed, 125 insertions(+), 2 deletions(-) create mode 100644 docs/concepts/storage/dynamic-provisioning.md diff --git a/_data/concepts.yml b/_data/concepts.yml index 742f389f3a..0d3d7b6416 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -75,8 +75,7 @@ toc: section: - docs/concepts/storage/volumes.md - docs/concepts/storage/persistent-volumes.md - - title: Dynamic Provisioning - path: http://blog.kubernetes.io/2016/10/dynamic-provisioning-and-storage-in-kubernetes.html + - docs/concepts/storage/dynamic-provisioning.md - title: Cluster Administration section: diff --git a/docs/concepts/storage/dynamic-provisioning.md b/docs/concepts/storage/dynamic-provisioning.md new file mode 100644 index 0000000000..6b60989208 --- /dev/null +++ b/docs/concepts/storage/dynamic-provisioning.md @@ -0,0 +1,124 @@ +--- +approvers: +- saad-ali +title: Dynamic Volume Provisioning +--- + +{% capture overview %} + +Dynamic volume provisioning allows storage volumes to be created on-demand. +Without dynamic provisioning, cluster administrators have to manually make +calls to their cloud or storage provider to create new storage volumes, and +then create [`PersistentVolume` objects](/docs/concepts/storage/persistent-volumes/) +to represent them in Kubernetes. The dynamic provisioning feature eliminates +the need for cluster administrators to pre-provision storage. Instead, it +automatically provisions storage when it is requested by users. + +{% endcapture %} + +{:toc} + +{% capture body %} + +## Background + +The implementation of dynamic volume provisioning is based on the API object `StorageClass` +from the API group `storage.k8s.io`. A cluster administrator can define as many +`StorageClass` objects as needed, each specifying a *volume plugin* (aka +*provisioner*) that provisions a volume and the set of parameters to pass to +that provisioner when provisioning. +A cluster administrator can define and expose multiple flavors of storage (from +the same or different storage systems) within a cluster, each with a custom set +of parameters. This design also ensures that end users don’t have to worry +about the the complexity and nuances of how storage is provisioned, but still +have the ability to select from multiple storage options. + +More information on storage classes can be found +[here](/docs/concepts/storage/persistent-volumes/#storageclasses). + +## Enabling Dynamic Provisioning + +To enable dynamic provisioning, a cluster administrator needs to pre-create +one or more StorageClass objects for users. +StorageClass objects define which provisioner should be used and what parameters +should be passed to that provisioner when dynamic provisioning is invoked. +The following manifest creates a storage class "slow" which provisions standard +disk-like persistent disks. + +```yaml +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: slow +provisioner: kubernetes.io/gce-pd +parameters: + type: pd-standard +``` + +The following manifest creates a storage class "fast" which provisions +SSD-like persistent disks. + +```yaml +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: fast +provisioner: kubernetes.io/gce-pd +parameters: + type: pd-ssd +``` + +## Using Dynamic Provisioning + +Users request dynamically provisioned storage by including a storage class in +their `PersistentVolumeClaim`. Before Kubernetes v1.6, this was done via the +`volume.beta.kubernetes.io/storage-class` annotation. However, this annotation +is deprecated since v1.6. Users now can and should instead use the +`storageClassName` field of the `PersistentVolumeClaim` object. The value of +this field must match the name of a `StorageClass` configured by the +administrator (see [below](#enabling-dynamic-provisioning)). + +To select the “fast” storage class, for example, a user would create the +following `PersistentVolumeClaim`: + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: claim1 +spec: + accessModes: + - ReadWriteOnce + storageClassName: fast + resources: + requests: + storage: 30Gi +``` + +This claim results in an SSD-like Persistent Disk being automatically +provisioned. When the claim is deleted, the volume is destroyed. + +## Defaulting Behavior + +Dynamic provisioning can be enabled on a cluster such that all claims are +dynamically provisioned if no storage class is specified. A cluster administrator +can enable this behavior by: + +- Marking one `StorageClass` object as *default*; +- Making sure that the [`DefaultStorageClass` admission controller](/docs/admin/admission-controllers/#defaultstorageclass) + is enabled on the API server. + +An administrator can mark a specific `StorageClass` as default by adding the +`storageclass.kubernetes.io/is-default-class` annotation to it. +When a default `StorageClass` exists in a cluster and a user creates a +`PersistentVolumeClaim` with `storageClassName` unspecified, the +`DefaultStorageClass` admission controller automatically adds the +`storageClassName` field pointing to the default storage class. + +Note that there can be at most one *default* storage class on a cluster, or +a `PersistentVolumeClaim` with `storageClassName` explicitly specified cannot +be created. + +{% endcapture %} + +{% include templates/concept.md %} From 33aa282480355c1da8a89b8026d49078984c0372 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Mon, 6 Nov 2017 14:39:41 +0800 Subject: [PATCH 02/53] Document the EventRateLimit admission controller --- docs/admin/admission-controllers.md | 36 +++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/admin/admission-controllers.md b/docs/admin/admission-controllers.md index 631389f234..39edefa740 100644 --- a/docs/admin/admission-controllers.md +++ b/docs/admin/admission-controllers.md @@ -100,6 +100,42 @@ If your cluster supports containers that run with escalated privileges, and you restrict the ability of end-users to exec commands in those containers, we strongly encourage enabling this plug-in. +### EventRateLimit (alpha) + +This plug-in is introduced in v1.9 to mitigate the problem where the API server gets flooded by +event requests. The cluster admin can specify event rate limits by: + + * Ensuring that `eventratelimit.admission.k8s.io/v1alpha1=true` is included in the + `--runtime-config` flag for the API server; + * Enabling the `EventRateLimit` admission controller; + * Including a `EventRateLimit` configuration in the file provided to the API + server's command line flag `--admission-control-config-file`. + +There are four types of limits that can be specified in the configuration: + + * `Server`: All event requests received by the API server share a single bucket. + * `Namespace`: Each namespace has a dedicated bucket. + * `User`: Each user is allocated a bucket. + * `SourceAndObject`: A bucket is assigned by each combination of source and + involved object of the event. + +Below is a sample snippet for such a configuration: + +```yaml +EventRateLimit: + limits: + - type: Namespace + qps: 50 + burst: 100 + cacheSize: 2000 + - type: User + qps: 10 + burst: 50 +``` + +See the [EventRateLimit proposal](https://git.k8s.io/community/contributors/design-proposals/api-machinery/admission_control_event_rate_limit.md) +for more details. + ### GenericAdmissionWebhook (alpha) This plug-in is related to the [Dynamic Admission Control](/docs/admin/extensible-admission-controllers) From a7c8e8cce6ed650af1e3fc12b052cee8f6fff658 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Mon, 13 Nov 2017 11:34:02 +0800 Subject: [PATCH 03/53] Document terminationMessagePolicy --- .../determine-reason-pod-failure.md | 43 ++++++++++++------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/docs/tasks/debug-application-cluster/determine-reason-pod-failure.md b/docs/tasks/debug-application-cluster/determine-reason-pod-failure.md index 74dff233ef..b5f2ac7914 100644 --- a/docs/tasks/debug-application-cluster/determine-reason-pod-failure.md +++ b/docs/tasks/debug-application-cluster/determine-reason-pod-failure.md @@ -75,25 +75,36 @@ only the termination message: {% raw %} kubectl get pod termination-demo -o go-template="{{range .status.containerStatuses}}{{.lastState.terminated.message}}{{end}}"{% endraw %} ``` -## Setting the termination log file +## Customizing the termination message -By default Kubernetes retrieves termination messages from -`/dev/termination-log`. To change this to a different file, -specify a `terminationMessagePath` field for your Container. +Kubernetes retrieves termination messages from the termination message file +specified in the `terminationMessagePath` field of a Container, which as a default +value of `/dev/termination-log`. By customizing this field, you can tell Kubernetes +to use a different file. Kubernetes use the contents from the specified file to +populate the Container's status message on both success and failure. -For example, suppose your Container writes termination messages to -`/tmp/my-log`, and you want Kubernetes to retrieve those messages. -Set `terminationMessagePath` as shown here: +In the following example, the container writes termination messages to +`/tmp/my-log` for Kubernetes to retrieve: - apiVersion: v1 - kind: Pod - metadata: - name: msg-path-demo - spec: - containers: - - name: msg-path-demo-container - image: debian - terminationMessagePath: "/tmp/my-log" +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: msg-path-demo +spec: + containers: + - name: msg-path-demo-container + image: debian + terminationMessagePath: "/tmp/my-log" +``` + +Moreover, users can set the `terminationMessagePolicy` field of a Container for +further customization. This field defaults to "`File`" which means the termination +messages are retrieved only from the termination message file. By setting the +`terminationMessagePolicy` to "`FallbackToLogsOnError`", you can tell Kubernetes +to use the last chunk of container log output if the termination message file +is empty and the container exited with an error. The log output is limited to +2048 bytes or 80 lines, whichever is smaller. {% endcapture %} From 5e4e68576c7d83d2af8a7d5bf6476e44c8f28523 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Mon, 13 Nov 2017 15:23:49 +0800 Subject: [PATCH 04/53] Add link to glossary page --- docs/tutorials/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 09c9ad91ea..1ad6870039 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -6,6 +6,8 @@ This section of the Kubernetes documentation contains tutorials. A tutorial shows how to accomplish a goal that is larger than a single [task](/docs/tasks/). Typically a tutorial has several sections, each of which has a sequence of steps. +Before walking through each tutorial, you may want to bookmark the +[Standardized Glossary](/docs/reference/glossary/) page for later references. * [Kubernetes Basics](/docs/tutorials/kubernetes-basics/) is an in-depth interactive tutorial that helps you understand the Kubernetes system and try out some basic Kubernetes features. From cf7ed4615e489db9198cd07b0c2b42b3b14c273a Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Thu, 9 Nov 2017 16:37:32 +0800 Subject: [PATCH 05/53] Add a note to pod preset --- docs/concepts/workloads/pods/podpreset.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/concepts/workloads/pods/podpreset.md b/docs/concepts/workloads/pods/podpreset.md index fa2aa5d25d..bf9ca2eb67 100644 --- a/docs/concepts/workloads/pods/podpreset.md +++ b/docs/concepts/workloads/pods/podpreset.md @@ -49,6 +49,11 @@ Pods, Kubernetes modifies the Pod Spec. For changes to `Env`, `EnvFrom`, and `VolumeMounts`, Kubernetes modifies the container spec for all containers in the Pod; for changes to `Volume`, Kubernetes modifies the Pod Spec. +**Note:** A Pod Preset is capable of modifying the `spec.containers` field in a +Pod spec when appropriate. *No* resource definition from the Pod Preset will be +applied to the `initContainers` field. +{: .note} + ### Disable Pod Preset for a Specific Pod There may be instances where you wish for a Pod to not be altered by any Pod From 9f758e644339807b363db1bc7d24c78815843bfa Mon Sep 17 00:00:00 2001 From: Qiming Date: Wed, 15 Nov 2017 02:48:53 +0800 Subject: [PATCH 06/53] Add warning about backoffLimit limitation (#6227) --- .../controllers/jobs-run-to-completion.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/concepts/workloads/controllers/jobs-run-to-completion.md b/docs/concepts/workloads/controllers/jobs-run-to-completion.md index 9af3d12971..a0276e8b32 100644 --- a/docs/concepts/workloads/controllers/jobs-run-to-completion.md +++ b/docs/concepts/workloads/controllers/jobs-run-to-completion.md @@ -198,9 +198,20 @@ multiple pods running at once. Therefore, your pods must also be tolerant of co ### Pod Backoff failure policy -There are situations where you want to fail a Job after some amount of retries due to a logical error in configuration etc. -To do so set `.spec.backoffLimit` to specify the number of retries before considering a Job as failed. -The back-off limit is set by default to 6. Failed Pods associated with the Job are recreated by the Job controller with an exponential back-off delay (10s, 20s, 40s ...) capped at six minutes, The back-off limit is reset if no new failed Pods appear before the Job's next status check. +There are situations where you want to fail a Job after some amount of retries +due to a logical error in configuration etc. +To do so, set `.spec.backoffLimit` to specify the number of retries before +considering a Job as failed. The back-off limit is set by default to 6. Failed +Pods associated with the Job are recreated by the Job controller with an +exponential back-off delay (10s, 20s, 40s ...) capped at six minutes, The +back-off limit is reset if no new failed Pods appear before the Job's next +status check. + +**Note:** Due to a known issue [#54870](https://github.com/kubernetes/kubernetes/issues/54870), +when the `spec.template.spec.restartPolicy` field is set to "`OnFailure`", the +back-off limit may be ineffective. As a short-term workaround, set the restart +policy for the embedded template to "`Never`". +{: .note} ## Job Termination and Cleanup From a20bf030a2df0d72baccbda849724e6f5b9e2ed0 Mon Sep 17 00:00:00 2001 From: Di Xu Date: Tue, 14 Nov 2017 13:35:17 -0600 Subject: [PATCH 07/53] add new examples for fieldSelector when using kubectl get (#6312) --- docs/user-guide/kubectl-cheatsheet.md | 3 +++ docs/user-guide/kubectl-overview.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/user-guide/kubectl-cheatsheet.md b/docs/user-guide/kubectl-cheatsheet.md index de6a9e1351..7e26083642 100644 --- a/docs/user-guide/kubectl-cheatsheet.md +++ b/docs/user-guide/kubectl-cheatsheet.md @@ -119,6 +119,9 @@ $ kubectl get pods --sort-by='.status.containerStatuses[0].restartCount' $ kubectl get pods --selector=app=cassandra rc -o \ jsonpath='{.items[*].metadata.labels.version}' +# Get all running pods in the namespace +$ kubectl get pods --field-selector=status.phase=Running + # Get ExternalIPs of all nodes $ kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}' diff --git a/docs/user-guide/kubectl-overview.md b/docs/user-guide/kubectl-overview.md index 3b46eccc0a..923a99558e 100644 --- a/docs/user-guide/kubectl-overview.md +++ b/docs/user-guide/kubectl-overview.md @@ -242,6 +242,9 @@ $ kubectl get rc,services // List all daemon sets, including uninitialized ones, in plain-text output format. $ kubectl get ds --include-uninitialized + +// List all pods running on node server01 +$ kubectl get pods --field-selector=spec.nodeName=server01 ``` `kubectl describe` - Display detailed state of one or more resources, including the uninitialized ones by default. From 71e634f75d039106571a35325ee211297fec151f Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Tue, 14 Nov 2017 13:37:49 -0600 Subject: [PATCH 08/53] Update create-cluster-kubeadm.md (#6308) Fix format. --- docs/setup/independent/create-cluster-kubeadm.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/setup/independent/create-cluster-kubeadm.md b/docs/setup/independent/create-cluster-kubeadm.md index 5590d16cbb..38aa122f2a 100644 --- a/docs/setup/independent/create-cluster-kubeadm.md +++ b/docs/setup/independent/create-cluster-kubeadm.md @@ -182,9 +182,9 @@ as root: ``` To make kubectl work for your non-root user, you might want to run these commands (which is also a part of the `kubeadm init` output): ``` - mkdir -p $HOME/.kube - sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config - sudo chown $(id -u):$(id -g) $HOME/.kube/config +mkdir -p $HOME/.kube +sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config +sudo chown $(id -u):$(id -g) $HOME/.kube/config ``` Alternatively, if you are the root user, you could run this: ``` @@ -226,7 +226,6 @@ kubectl apply -f **NOTE:** You can install **only one** pod network per cluster. - {% capture choose %} Please select one of the tabs to see installation instructions for the respective third-party Pod Network Provider. {% endcapture %} From 66c625fdf0f2fe10bee07bc279adc01fbfd58565 Mon Sep 17 00:00:00 2001 From: Cheryl Hung Date: Tue, 14 Nov 2017 21:06:31 +0000 Subject: [PATCH 09/53] Add StorageOS provisioner to comparison table (#6315) --- docs/concepts/storage/persistent-volumes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md index 31b81404a3..f1eb6c971f 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/docs/concepts/storage/persistent-volumes.md @@ -474,6 +474,7 @@ for provisioning PVs. This field must be specified. | VsphereVolume | ✓ | [vSphere](#vsphere) | | PortworxVolume | ✓ | [Portworx Volume](#portworx-volume) | | ScaleIO | ✓ | [ScaleIO](#scaleio) | +| StorageOS | ✓ | [StorageOS](#storageos) | You are not restricted to specifying the "internal" provisioners listed here (whose names are prefixed with "kubernetes.io" and shipped From 037341f3ae91bf85b213bae2d2bbf33e93f399bc Mon Sep 17 00:00:00 2001 From: Tomasz Prus Date: Tue, 14 Nov 2017 22:08:27 +0100 Subject: [PATCH 10/53] fix: unit for "kilo" is lowercase (#6314) --- .../configuration/manage-compute-resources-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/configuration/manage-compute-resources-container.md b/docs/concepts/configuration/manage-compute-resources-container.md index 9f784a2d9e..8508f6642a 100644 --- a/docs/concepts/configuration/manage-compute-resources-container.md +++ b/docs/concepts/configuration/manage-compute-resources-container.md @@ -70,7 +70,7 @@ CPU is always requested as an absolute quantity, never as a relative quantity; Limits and requests for `memory` are measured in bytes. You can express memory as a plain integer or as a fixed-point integer using one of these suffixes: -E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, +E, P, T, G, M, k. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. For example, the following represent roughly the same value: ```shell From 09a1b70681711bf13c63676acd5991c60bd7c2f8 Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Tue, 14 Nov 2017 15:09:00 -0600 Subject: [PATCH 11/53] Update cloud-providers.md (#6313) Fix format. --- docs/concepts/cluster-administration/cloud-providers.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/concepts/cluster-administration/cloud-providers.md b/docs/concepts/cluster-administration/cloud-providers.md index 5db0a3ac3d..739476217c 100644 --- a/docs/concepts/cluster-administration/cloud-providers.md +++ b/docs/concepts/cluster-administration/cloud-providers.md @@ -71,9 +71,11 @@ the underlying cloud, where available: † Block Storage V1 API support is deprecated, support for Block Storage V3 will be added in the future. + ‡ Identity V2 API support is deprecated and will be removed from the provider in a future release. As of the "Queens" release OpenStack will no longer expose the Identity V2 API. + § Load Balancing V1 API support is deprecated and will be removed from the provider in a future release. From ba7c3005c92fe5935979f8155eed85377329171a Mon Sep 17 00:00:00 2001 From: wackxu Date: Wed, 15 Nov 2017 14:12:11 +0800 Subject: [PATCH 12/53] move some generated file to docs/reference/generated directory --- _data/reference.yml | 12 ++++++------ _redirects | 7 +++++++ .../generated}/cloud-controller-manager.md | 0 .../{admin => reference/generated}/kube-apiserver.md | 0 .../generated}/kube-controller-manager.md | 0 docs/{admin => reference/generated}/kube-proxy.md | 0 .../{admin => reference/generated}/kube-scheduler.md | 0 docs/{admin => reference/generated}/kubelet.md | 0 8 files changed, 13 insertions(+), 6 deletions(-) rename docs/{admin => reference/generated}/cloud-controller-manager.md (100%) rename docs/{admin => reference/generated}/kube-apiserver.md (100%) rename docs/{admin => reference/generated}/kube-controller-manager.md (100%) rename docs/{admin => reference/generated}/kube-proxy.md (100%) rename docs/{admin => reference/generated}/kube-scheduler.md (100%) rename docs/{admin => reference/generated}/kubelet.md (100%) diff --git a/_data/reference.yml b/_data/reference.yml index 0884201608..0db9d6ef0f 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -66,7 +66,7 @@ toc: - title: Cloud Controller Manager section: - - docs/admin/cloud-controller-manager.md + - docs/reference/generated/cloud-controller-manager.md - title: Setup Tools section: @@ -82,12 +82,12 @@ toc: - title: Config Reference section: - - docs/admin/kubelet.md + - docs/reference/generated/kubelet.md - docs/admin/kubelet-authentication-authorization.md - - docs/admin/kube-apiserver.md - - docs/admin/kube-controller-manager.md - - docs/admin/kube-proxy.md - - docs/admin/kube-scheduler.md + - docs/reference/generated/kube-apiserver.md + - docs/reference/generated/kube-controller-manager.md + - docs/reference/generated/kube-proxy.md + - docs/reference/generated/kube-scheduler.md - docs/admin/kubelet-tls-bootstrapping.md - docs/admin/federation-apiserver.md - docs/admin/federation-controller-manager.md diff --git a/_redirects b/_redirects index b7e3bc1af9..081590f6d4 100644 --- a/_redirects +++ b/_redirects @@ -410,3 +410,10 @@ /v1.1/docs/getting-started-guides/ /docs/tutorials/kubernetes-basics/ 301 https://kubernetes-io-v1-7.netlify.com/* https://v1-7.docs.kubernetes.io/"splat 301 + +/docs/admin/cloud-controller-manager/ /docs/reference/generated/cloud-controller-manager/ 301 +/docs/admin/kube-apiserver/ /docs/reference/generated/kube-apiserver/ 301 +/docs/admin/kube-controller-manager/ /docs/reference/generated/kube-controller-manager/ 301 +/docs/admin/kube-proxy/ /docs/reference/generated/kube-proxy/ 301 +/docs/admin/kube-scheduler/ /docs/reference/generated/kube-scheduler/ 301 +/docs/admin/kube-scheduler/ /docs/reference/generated/kube-scheduler/ 301 \ No newline at end of file diff --git a/docs/admin/cloud-controller-manager.md b/docs/reference/generated/cloud-controller-manager.md similarity index 100% rename from docs/admin/cloud-controller-manager.md rename to docs/reference/generated/cloud-controller-manager.md diff --git a/docs/admin/kube-apiserver.md b/docs/reference/generated/kube-apiserver.md similarity index 100% rename from docs/admin/kube-apiserver.md rename to docs/reference/generated/kube-apiserver.md diff --git a/docs/admin/kube-controller-manager.md b/docs/reference/generated/kube-controller-manager.md similarity index 100% rename from docs/admin/kube-controller-manager.md rename to docs/reference/generated/kube-controller-manager.md diff --git a/docs/admin/kube-proxy.md b/docs/reference/generated/kube-proxy.md similarity index 100% rename from docs/admin/kube-proxy.md rename to docs/reference/generated/kube-proxy.md diff --git a/docs/admin/kube-scheduler.md b/docs/reference/generated/kube-scheduler.md similarity index 100% rename from docs/admin/kube-scheduler.md rename to docs/reference/generated/kube-scheduler.md diff --git a/docs/admin/kubelet.md b/docs/reference/generated/kubelet.md similarity index 100% rename from docs/admin/kubelet.md rename to docs/reference/generated/kubelet.md From 9853fed7fd4d2e9ea71340b2ddbc6b55d3dddade Mon Sep 17 00:00:00 2001 From: lichuqiang Date: Tue, 14 Nov 2017 11:22:37 +0800 Subject: [PATCH 13/53] translate doc rollback-daemon-set into Chinese --- .../manage-daemon/rollback-daemon-set.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 cn/docs/tasks/manage-daemon/rollback-daemon-set.md diff --git a/cn/docs/tasks/manage-daemon/rollback-daemon-set.md b/cn/docs/tasks/manage-daemon/rollback-daemon-set.md new file mode 100644 index 0000000000..c9684be648 --- /dev/null +++ b/cn/docs/tasks/manage-daemon/rollback-daemon-set.md @@ -0,0 +1,138 @@ +--- +approvers: +- janetkuo +title: 对 DaemonSet 执行回滚 +--- + +{% capture overview %} + +本文展示了如何对 DaemonSet 执行回滚。 + +{% endcapture %} + + +{% capture prerequisites %} + +* DaemonSet 滚动升级历史和 DaemonSet 回滚特性仅在 Kubernetes 1.7 及以后版本的 `kubectl` 中支持。 +* 确保您了解如何 [对 DaemonSet 执行滚动升级](/docs/tasks/manage-daemon/update-daemon-set/)。 + +{% endcapture %} + + +{% capture steps %} + +## 对 DaemonSet 执行回滚 + +### 步骤 1： 找到想要 DaemonSet 回滚到的历史版本（revision） + +如果只想回滚到最后一个版本，可以跳过这一步。 + +列出 DaemonSet 的所有版本： + +```shell +kubectl rollout history daemonset +``` + +该命令返回 DaemonSet 版本列表： + +```shell +daemonsets "" +REVISION CHANGE-CAUSE +1 ... +2 ... +... +``` + +* 在创建时，DaemonSet 的变化原因从 `kubernetes.io/change-cause` 注解（annotation）复制到其版本中。 用户可以在 `kubectl` 中指定 `--record=true` ，将执行的命令记录在变化原因注解中。 + +执行以下命令，来查看指定版本的详细信息： + +```shell +kubectl rollout history daemonset --revision=1 +``` + +该命令返回相应版本的详细信息： + +```shell +daemonsets "" with revision #1 +Pod Template: +Labels: foo=bar +Containers: +app: + Image: ... + Port: ... + Environment: ... + Mounts: ... +Volumes: ... +``` + +### 步骤 2： 回滚到指定版本 + +```shell +# 在 --to-revision 中指定您从步骤 1 中获取的版本序号 +kubectl rollout undo daemonset --to-revision= +``` + +如果成功，命令会返回： + +```shell +daemonset "" rolled back +``` + +如果 `--to-revision` 参数未指定，将选中最近的版本。 + +### 步骤 3： 观察 DaemonSet 回滚进度 + +`kubectl rollout undo daemonset` 向服务器表明启动 DaemonSet 回滚。 真正的回滚是在服务器端异步完成的。 + +执行以下命令，来观察 DaemonSet 回滚进度： + +```shell +kubectl rollout status ds/ +``` + +回滚完成时，输出形如： + +```shell +daemonset "" successfully rolled out +``` + +{% endcapture %} + + +{% capture discussion %} + +## 理解 DaemonSet 版本 + +在前面的 `kubectl rollout history` 步骤中，您获得了一个版本列表，每个版本都存储在名为 + `ControllerRevision` 的资源中。 `ControllerRevision` 仅在 Kubernetes 1.7 及以后的版本中可用。 + +查找原始的版本资源，来查看每个版本中存储了什么内容： + +```shell +kubectl get controllerrevision -l = +``` + +该命令返回 `ControllerRevisions` 列表： + +```shell +NAME CONTROLLER REVISION AGE +- DaemonSet/ 1 1h +- DaemonSet/ 2 1h +``` + +每个 `ControllerRevision` 中存储了相应 DaemonSet 版本的注解和模板。 + +`kubectl rollout undo` 采用特定 `ControllerRevision` ，并用 +`ControllerRevision` 中存储的模板代替 DaemonSet 的模板。 +`kubectl rollout undo` 相当于通过其他命令（如 `kubectl edit` 或 `kubectl apply`）将 DaemonSet 模板更新至先前的版本。 + +注意 DaemonSet 版本只会向前滚动。 也就是说，回滚完成后，所回滚到的 `ControllerRevision` 版本号 (`.revision` 字段) 会增加。 例如，如果用户在系统中有版本 1 和版本 2，并从版本 2 回滚到版本 1 ，带有 `.revision: 1` 的`ControllerRevision` 将变为 `.revision: 3`。 + +## 故障排除 + +* 查看 [DaemonSet 滚动升级故障排除](/docs/tasks/manage-daemon/update-daemon-set/#troubleshooting)。 + +{% endcapture %} + +{% include templates/task.md %} From 134507dbc11593666b69a0d4f3dea653f9598058 Mon Sep 17 00:00:00 2001 From: XsWack Date: Wed, 15 Nov 2017 17:16:14 +0800 Subject: [PATCH 14/53] move kubefed to /docs/reference/generated directory (#6325) * move kubefed to docs/reference/generated * update _redirects and _data/referenerce.yaml --- _data/reference.yml | 12 ++++++------ _redirects | 7 +++++++ docs/{admin => reference/generated}/kubefed.md | 0 docs/{admin => reference/generated}/kubefed_init.md | 0 docs/{admin => reference/generated}/kubefed_join.md | 0 .../generated}/kubefed_options.md | 0 .../{admin => reference/generated}/kubefed_unjoin.md | 0 .../generated}/kubefed_version.md | 0 8 files changed, 13 insertions(+), 6 deletions(-) rename docs/{admin => reference/generated}/kubefed.md (100%) rename docs/{admin => reference/generated}/kubefed_init.md (100%) rename docs/{admin => reference/generated}/kubefed_join.md (100%) rename docs/{admin => reference/generated}/kubefed_options.md (100%) rename docs/{admin => reference/generated}/kubefed_unjoin.md (100%) rename docs/{admin => reference/generated}/kubefed_version.md (100%) diff --git a/_data/reference.yml b/_data/reference.yml index 0884201608..7df5e8a79f 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -73,12 +73,12 @@ toc: - docs/admin/kubeadm.md - title: Kubefed section: - - docs/admin/kubefed.md - - docs/admin/kubefed_options.md - - docs/admin/kubefed_init.md - - docs/admin/kubefed_join.md - - docs/admin/kubefed_unjoin.md - - docs/admin/kubefed_version.md + - docs/reference/generated/kubefed.md + - docs/reference/generated/kubefed_options.md + - docs/reference/generated/kubefed_init.md + - docs/reference/generated/kubefed_join.md + - docs/reference/generated/kubefed_unjoin.md + - docs/reference/generated/kubefed_version.md - title: Config Reference section: diff --git a/_redirects b/_redirects index b7e3bc1af9..d0647d85ac 100644 --- a/_redirects +++ b/_redirects @@ -410,3 +410,10 @@ /v1.1/docs/getting-started-guides/ /docs/tutorials/kubernetes-basics/ 301 https://kubernetes-io-v1-7.netlify.com/* https://v1-7.docs.kubernetes.io/"splat 301 + +/docs/admin/kubefed/ /docs/reference/generated/kubefed/ 301 +/docs/admin/kubefed_init/ /docs/reference/generated/kubefed_init/ 301 +/docs/admin/kubefed_join/ /docs/reference/generated/kubefed_join/ 301 +/docs/admin/kubefed_options/ /docs/reference/generated/kubefed_options/ 301 +/docs/admin/kubefed_unjoin/ /docs/reference/generated/kubefed_unjoin/ 301 +/docs/admin/kubefed_version/ /docs/reference/generated/kubefed_version/ 301 \ No newline at end of file diff --git a/docs/admin/kubefed.md b/docs/reference/generated/kubefed.md similarity index 100% rename from docs/admin/kubefed.md rename to docs/reference/generated/kubefed.md diff --git a/docs/admin/kubefed_init.md b/docs/reference/generated/kubefed_init.md similarity index 100% rename from docs/admin/kubefed_init.md rename to docs/reference/generated/kubefed_init.md diff --git a/docs/admin/kubefed_join.md b/docs/reference/generated/kubefed_join.md similarity index 100% rename from docs/admin/kubefed_join.md rename to docs/reference/generated/kubefed_join.md diff --git a/docs/admin/kubefed_options.md b/docs/reference/generated/kubefed_options.md similarity index 100% rename from docs/admin/kubefed_options.md rename to docs/reference/generated/kubefed_options.md diff --git a/docs/admin/kubefed_unjoin.md b/docs/reference/generated/kubefed_unjoin.md similarity index 100% rename from docs/admin/kubefed_unjoin.md rename to docs/reference/generated/kubefed_unjoin.md diff --git a/docs/admin/kubefed_version.md b/docs/reference/generated/kubefed_version.md similarity index 100% rename from docs/admin/kubefed_version.md rename to docs/reference/generated/kubefed_version.md From 16f6a6159644245f0c731df470d2fce72742c86a Mon Sep 17 00:00:00 2001 From: XsWack Date: Wed, 15 Nov 2017 17:45:12 +0800 Subject: [PATCH 15/53] move federation-apiserver federation-controller-manager to /docs/reference/generated directory (#6327) * move federation-apiserver federation-controller-manager to /docs/reference/generated directory * update _redirects and _data/referenerce.yaml --- _data/reference.yml | 4 ++-- _redirects | 7 ++++++- .../{admin => reference/generated}/federation-apiserver.md | 0 .../generated}/federation-controller-manager.md | 0 4 files changed, 8 insertions(+), 3 deletions(-) rename docs/{admin => reference/generated}/federation-apiserver.md (100%) rename docs/{admin => reference/generated}/federation-controller-manager.md (100%) diff --git a/_data/reference.yml b/_data/reference.yml index 7df5e8a79f..bd2e8cc368 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -89,8 +89,8 @@ toc: - docs/admin/kube-proxy.md - docs/admin/kube-scheduler.md - docs/admin/kubelet-tls-bootstrapping.md - - docs/admin/federation-apiserver.md - - docs/admin/federation-controller-manager.md + - docs/reference/generated/federation-apiserver.md + - docs/reference/generated/federation-controller-manager.md - title: Kubernetes Design Docs section: diff --git a/_redirects b/_redirects index d0647d85ac..12512f33d0 100644 --- a/_redirects +++ b/_redirects @@ -411,9 +411,14 @@ https://kubernetes-io-v1-7.netlify.com/* https://v1-7.docs.kubernetes.io/"splat 301 + +/docs/admin/federation-controller-manager/ /docs/reference/generated/federation-controller-manager/ 301 +/docs/admin/federation-apiserver/ /docs/reference/generated/federation-apiserver/ 301 + /docs/admin/kubefed/ /docs/reference/generated/kubefed/ 301 /docs/admin/kubefed_init/ /docs/reference/generated/kubefed_init/ 301 /docs/admin/kubefed_join/ /docs/reference/generated/kubefed_join/ 301 /docs/admin/kubefed_options/ /docs/reference/generated/kubefed_options/ 301 /docs/admin/kubefed_unjoin/ /docs/reference/generated/kubefed_unjoin/ 301 -/docs/admin/kubefed_version/ /docs/reference/generated/kubefed_version/ 301 \ No newline at end of file +/docs/admin/kubefed_version/ /docs/reference/generated/kubefed_version/ 301 + diff --git a/docs/admin/federation-apiserver.md b/docs/reference/generated/federation-apiserver.md similarity index 100% rename from docs/admin/federation-apiserver.md rename to docs/reference/generated/federation-apiserver.md diff --git a/docs/admin/federation-controller-manager.md b/docs/reference/generated/federation-controller-manager.md similarity index 100% rename from docs/admin/federation-controller-manager.md rename to docs/reference/generated/federation-controller-manager.md From c531e1af40dc03a96a55c13da6763bee5fef3572 Mon Sep 17 00:00:00 2001 From: XsWack Date: Wed, 15 Nov 2017 17:49:25 +0800 Subject: [PATCH 16/53] Update _redirects --- _redirects | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_redirects b/_redirects index fc12a74fc2..48ec59613a 100644 --- a/_redirects +++ b/_redirects @@ -421,7 +421,7 @@ https://kubernetes-io-v1-7.netlify.com/* https://v1-7.docs.kubernetes.io/"spl /docs/admin/federation-apiserver/ /docs/reference/generated/federation-apiserver/ 301 /docs/admin/kubefed/ /docs/reference/generated/kubefed/ 301 /docs/admin/kubefed_init/ /docs/reference/generated/kubefed_init/ 301 -/docs/admin/kubefed_join/ /docs/reference/generated/kubefed_join/ 30 +/docs/admin/kubefed_join/ /docs/reference/generated/kubefed_join/ 301 /docs/admin/kubefed_options/ /docs/reference/generated/kubefed_options/ 301 /docs/admin/kubefed_unjoin/ /docs/reference/generated/kubefed_unjoin/ 301 /docs/admin/kubefed_version/ /docs/reference/generated/kubefed_version/ 301 From da6e3216696124ac92c96ff50d5290307bddb86d Mon Sep 17 00:00:00 2001 From: XsWack Date: Thu, 16 Nov 2017 01:43:17 +0800 Subject: [PATCH 17/53] move kubeadm to /docs/reference/generated directory (#6326) --- _data/reference.yml | 2 +- _redirects | 3 ++- docs/{admin => reference/generated}/kubeadm.md | 0 3 files changed, 3 insertions(+), 2 deletions(-) rename docs/{admin => reference/generated}/kubeadm.md (100%) diff --git a/_data/reference.yml b/_data/reference.yml index bd2e8cc368..d83da4785f 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -70,7 +70,7 @@ toc: - title: Setup Tools section: - - docs/admin/kubeadm.md + - docs/reference/generated/kubeadm.md - title: Kubefed section: - docs/reference/generated/kubefed.md diff --git a/_redirects b/_redirects index 12512f33d0..890f6027eb 100644 --- a/_redirects +++ b/_redirects @@ -412,9 +412,10 @@ https://kubernetes-io-v1-7.netlify.com/* https://v1-7.docs.kubernetes.io/"splat 301 + +/docs/admin/kubeadm/ /docs/reference/generated/kubeadm/ 301 /docs/admin/federation-controller-manager/ /docs/reference/generated/federation-controller-manager/ 301 /docs/admin/federation-apiserver/ /docs/reference/generated/federation-apiserver/ 301 - /docs/admin/kubefed/ /docs/reference/generated/kubefed/ 301 /docs/admin/kubefed_init/ /docs/reference/generated/kubefed_init/ 301 /docs/admin/kubefed_join/ /docs/reference/generated/kubefed_join/ 301 diff --git a/docs/admin/kubeadm.md b/docs/reference/generated/kubeadm.md similarity index 100% rename from docs/admin/kubeadm.md rename to docs/reference/generated/kubeadm.md From 3acd89b0b8dcd02bdb0b05e295150b20aa8b56c6 Mon Sep 17 00:00:00 2001 From: GabrielSVinha Date: Wed, 15 Nov 2017 21:03:10 -0300 Subject: [PATCH 18/53] Add namespaces to kubefed docs --- docs/tasks/federation/set-up-cluster-federation-kubefed.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/tasks/federation/set-up-cluster-federation-kubefed.md b/docs/tasks/federation/set-up-cluster-federation-kubefed.md index 0bee5d7818..a615cdbf25 100644 --- a/docs/tasks/federation/set-up-cluster-federation-kubefed.md +++ b/docs/tasks/federation/set-up-cluster-federation-kubefed.md @@ -493,5 +493,8 @@ federation control plane's etcd. You can delete the federation namespace by running the following command: ``` -kubectl delete ns federation-system +kubectl delete ns federation-system --context=rivendell ``` + +Note that `rivendell` is the host cluster name, replace that with the appropriate name in your configuration. + From 5ffbc56dd0c0c0201a18e521336f78b9d348f8de Mon Sep 17 00:00:00 2001 From: craigbox Date: Wed, 15 Nov 2017 22:18:59 -0200 Subject: [PATCH 19/53] Update gce.md fix link to GKE --- docs/getting-started-guides/gce.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started-guides/gce.md b/docs/getting-started-guides/gce.md index 136239146a..d513e33406 100644 --- a/docs/getting-started-guides/gce.md +++ b/docs/getting-started-guides/gce.md @@ -14,7 +14,7 @@ The example below creates a Kubernetes cluster with 4 worker node Virtual Machin ### Before you start -If you want a simplified getting started experience and GUI for managing clusters, please consider trying [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/internal-load-balancing) for hosted cluster installation and management. +If you want a simplified getting started experience and GUI for managing clusters, please consider trying [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) for hosted cluster installation and management. For an easy way to experiment with the Kubernetes development environment, [click here](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/kubernetes/kubernetes&page=editor&open_in_editor=README.md) to open a Google Cloud Shell with an auto-cloned copy of the Kubernetes source repo. From 47a07818640f4ce10b00e861b7ef5de8dde4c088 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Thu, 16 Nov 2017 16:43:06 +0800 Subject: [PATCH 20/53] Note on creating LimitRange for GPU, huge-pages resources --- docs/tasks/administer-cluster/cpu-constraint-namespace.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/tasks/administer-cluster/cpu-constraint-namespace.md b/docs/tasks/administer-cluster/cpu-constraint-namespace.md index 40c4961832..f5f4d7dadd 100644 --- a/docs/tasks/administer-cluster/cpu-constraint-namespace.md +++ b/docs/tasks/administer-cluster/cpu-constraint-namespace.md @@ -79,6 +79,11 @@ CPU request and limit to the Container. * Verify that the Container specifies a CPU limit that is less than or equal to 800 millicpu. +**Note:** When creating a `LimitRange` object, you can specify limits on huge-pages +or GPUs as well. However, when both `default` and `defaultRequest` are specified +on these resources, the two values must be the same. +{: .note} + Here's the configuration file for a Pod that has one Container. The Container manifest specifies a CPU request of 500 millicpu and a CPU limit of 800 millicpu. These satisfy the minimum and maximum CPU constraints imposed by the LimitRange. From 3e4e1971b29fead3e25c9c596c74db0741c72f89 Mon Sep 17 00:00:00 2001 From: lichuqiang Date: Thu, 16 Nov 2017 16:53:25 +0800 Subject: [PATCH 21/53] translate doc podpreset in concepts into Chinese --- cn/docs/concepts/workloads/pods/podpreset.md | 70 ++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 cn/docs/concepts/workloads/pods/podpreset.md diff --git a/cn/docs/concepts/workloads/pods/podpreset.md b/cn/docs/concepts/workloads/pods/podpreset.md new file mode 100644 index 0000000000..76d2d778be --- /dev/null +++ b/cn/docs/concepts/workloads/pods/podpreset.md @@ -0,0 +1,70 @@ +--- +approvers: +- jessfraz +title: Pod Preset +--- + +{% capture overview %} +本文提供了 PodPreset 的概述。 在 pod 创建时，用户可以使用 `podpreset` 对象将特定信息注入 +pod 中，这些信息可以包括 secret、 卷、卷挂载和环境变量。 +{% endcapture %} + +{:toc} + +{% capture body %} +## 理解 Pod Preset + +`Pod Preset` 是一种 API 资源，在 pod 创建时，用户可以用它将额外的运行时需求信息注入 pod。 +使用[标签选择器（label selector）](/docs/concepts/overview/working-with-objects/labels/#label-selectors)来指定 Pod Preset 所适用的 pod。 + +使用 Pod Preset 使得 pod 模板编写者不必显式地为每个 pod 设置信息。 +这样，使用特定服务的 pod 模板编写者不需要了解该服务的所有细节。 + +了解更多的相关背景信息，请参考 [ PodPreset 设计提案](https://git.k8s.io/community/contributors/design-proposals/service-catalog/pod-preset.md)。 + +## PodPreset 如何工作 + +Kubernetes 提供了准入控制器 (`PodPreset`)，该控制器被启用时，会将 Pod Preset +应用于接收到的 pod 创建请求中。 +当出现 pod 创建请求时，系统会执行以下操作： + +1. 检索所有可用 `PodPresets` 。 +1. 检查 `PodPreset` 的标签选择器与要创建的 pod 的标签是否匹配。 +1. 尝试合并 `PodPreset` 中定义的各种资源，并注入要创建的 pod。 +1. 发生错误时抛出事件，该事件记录了 pod 信息合并错误，同时在 _不注入_ `PodPreset` 信息的情况下创建 pod。 +1. 为改动的 pod spec 添加注解，来表明它被 `PodPreset` 所修改。 注解形如： +`podpreset.admission.kubernetes.io/podpreset-": ""`。 + +一个 Pod 可能不与任何 Pod Preset 匹配，也可能匹配多个 Pod Preset。 同时，一个 `PodPreset` +可能不应用于任何 Pod，也可能应用于多个 Pod。 当 `PodPreset` 应用于一个或多个 Pod 时，Kubernetes +修改 pod spec。 对于 `Env`、 `EnvFrom` 和 `VolumeMounts` 的改动， Kubernetes 修改 pod +中所有容器的规格，对于卷的改动，Kubernetes 修改 Pod spec。 + +**注意：** Pod Preset 能够在适当的时候修改 Pod spec 的 `spec.containers` 字段， +但是不会应用于 `initContainers` 字段。 +{: .note} + +### 为特定 Pod 禁用 Pod Preset + +在一些情况下，用户不希望 pod 被 pod preset 所改动，这时，用户可以在 pod spec 中添加形如 + `podpreset.admission.kubernetes.io/exclude: "true"` 的注解。 + +## 启用 Pod Preset + +为了在集群中使用 Pod Preset，必须确保以下几点： + +1. 已启用 api 类型 `settings.k8s.io/v1alpha1/podpreset`。 这可以通过在 API 服务器的 + `--runtime-config` 配置项中包含 `settings.k8s.io/v1alpha1=true` 来实现。 +1. 已启用准入控制器 `PodPreset`。 启用的一种方式是在 API 服务器的 `--admission-control` + 配置项中包含 `PodPreset` 。 +1. 已经通过在相应的名字空间中创建 `PodPreset` 对象，定义了 Pod preset。 + +{% endcapture %} + +{% capture whatsnext %} + +* [使用 PodPreset 将信息注入 Pods](/docs/tasks/inject-data-application/podpreset/) + +{% endcapture %} + +{% include templates/concept.md %} From e2bb1950f0039209bb48e16702f959463a29b206 Mon Sep 17 00:00:00 2001 From: lichuqiang Date: Thu, 16 Nov 2017 10:28:54 +0800 Subject: [PATCH 22/53] translate doc certificate-rotation into Chinese --- cn/docs/tasks/tls/certificate-rotation.md | 64 +++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 cn/docs/tasks/tls/certificate-rotation.md diff --git a/cn/docs/tasks/tls/certificate-rotation.md b/cn/docs/tasks/tls/certificate-rotation.md new file mode 100644 index 0000000000..726eb5bd73 --- /dev/null +++ b/cn/docs/tasks/tls/certificate-rotation.md @@ -0,0 +1,64 @@ +--- +approvers: +- jcbsmpsn +- mikedanese +title: 证书轮换 +--- + +{% capture overview %} +本文展示如何在 kubelet 中启用并配置证书轮换。 +{% endcapture %} + +{% capture prerequisites %} + +* 要求 Kubernetes 1.8.0 或更高的版本 + +* Kubelet 证书轮换在 1.8.0 版本中处于 beta 阶段, 这意味着该特性可能在没有通知的情况下发生变化。 + +{% endcapture %} + +{% capture steps %} + +## 概述 + +Kubelet 使用证书进行 Kubernetes API 的认证。 +默认情况下，这些证书的签发期限为一年，所以不需要太频繁地进行更新。 + +Kubernetes 1.8 版本中包含 beta 特性 [kubelet 证书轮换](/docs/tasks/administer-cluster/certificate-rotation/)， +在当前证书即将过期时， +将自动生成新的秘钥，并从 Kubernetes API 申请新的证书。 一旦新的证书可用，它将被用于与 +Kubernetes API 间的连接认证。 + +## 启用客户端证书轮换 + + `kubelet` 进程接收 `--rotate-certificates` 参数，该参数决定 kubelet 在当前使用的证书即将到期时， +是否会自动申请新的证书。 由于证书轮换是 beta 特性，必须通过参数 `--feature-gates=RotateKubeletClientCertificate=true` 进行启用。 + + +`kube-controller-manager` 进程接收 +`--experimental-cluster-signing-duration` 参数，该参数控制证书签发的有效期限。 + +## 理解证书轮换配置 + +当 kubelet 启动时，如被配置为自举（使用`--bootstrap-kubeconfig` 参数），kubelet 会使用其初始证书连接到 +Kubernetes API ，并发送证书签名的请求。 可以通过以下方式查看证书签名请求的状态： + +```sh +kubectl get csr +``` + +最初，来自节点上 kubelet 的证书签名请求处于 `Pending` 状态。 如果证书签名请求满足特定条件， +控制器管理器会自动批准，此时请求会处于 `Approved` 状态。 接下来，控制器管理器会签署证书， +证书的有效期限由 `--experimental-cluster-signing-duration` 参数指定，签署的证书会被附加到证书签名请求中。 + +Kubelet 会从 Kubernetes API 取回签署的证书，并将其写入磁盘，存储位置通过 `--cert-dir` 参数指定。 +然后 kubelet 会使用新的证书连接到 Kubernetes API。 + +当签署的证书即将到期时，kubelet 会使用 Kubernetes API，发起新的证书签名请求。 +同样地，控制器管理器会自动批准证书请求，并将签署的证书附加到证书签名请求中。 Kubelet +会从 Kubernetes API 取回签署的证书，并将其写入磁盘。 然后它会更新与 Kubernetes API +的连接，使用新的证书重新连接到 Kubernetes API。 + +{% endcapture %} + +{% include templates/task.md %} From 89e902d76c162ece826a393d01502f5f670b010a Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Thu, 16 Nov 2017 20:05:32 +0800 Subject: [PATCH 23/53] Update cluster-management.md Fix dead link. --- docs/tasks/administer-cluster/cluster-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tasks/administer-cluster/cluster-management.md b/docs/tasks/administer-cluster/cluster-management.md index b05718e119..6f8d1a7ede 100644 --- a/docs/tasks/administer-cluster/cluster-management.md +++ b/docs/tasks/administer-cluster/cluster-management.md @@ -53,7 +53,7 @@ cluster/gce/upgrade.sh release/stable Google Kubernetes Engine automatically updates master components (e.g. `kube-apiserver`, `kube-scheduler`) to the latest version. It also handles upgrading the operating system and other components that the master runs on. -The node upgrade process is user-initiated and is described in the [Google Kubernetes Engine documentation](https://cloud.google.com/kubernetes-engine//docs/clusters/upgrade). +The node upgrade process is user-initiated and is described in the [Google Kubernetes Engine documentation](https://cloud.google.com/kubernetes-engine/docs/clusters/upgrade). ### Upgrading clusters on other platforms From eac887d5924156f9b5431c8b15a724ed8df71f00 Mon Sep 17 00:00:00 2001 From: Stuart Harris Date: Thu, 16 Nov 2017 13:36:45 +0000 Subject: [PATCH 24/53] Use `echo -n` rather than `echo` to avoid trailing newline... ...during secret creation --- docs/user-guide/kubectl-cheatsheet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/kubectl-cheatsheet.md b/docs/user-guide/kubectl-cheatsheet.md index 7e26083642..2673a0af88 100644 --- a/docs/user-guide/kubectl-cheatsheet.md +++ b/docs/user-guide/kubectl-cheatsheet.md @@ -90,8 +90,8 @@ metadata: name: mysecret type: Opaque data: - password: $(echo "s33msi4" | base64) - username: $(echo "jane" | base64) + password: $(echo -n "s33msi4" | base64) + username: $(echo -n "jane" | base64) EOF ``` From 711ce0ce5cb842558b9710f52341eb17240cbc25 Mon Sep 17 00:00:00 2001 From: Tom Denham Date: Thu, 16 Nov 2017 10:55:17 -0700 Subject: [PATCH 25/53] Update flannel to version v0.9.1 This includes a single fix to improve compatibility with later versions of Docker. Release note: https://github.com/coreos/flannel/releases/tag/v0.9.1 --- docs/setup/independent/create-cluster-kubeadm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/independent/create-cluster-kubeadm.md b/docs/setup/independent/create-cluster-kubeadm.md index 38aa122f2a..9abd872e00 100644 --- a/docs/setup/independent/create-cluster-kubeadm.md +++ b/docs/setup/independent/create-cluster-kubeadm.md @@ -271,7 +271,7 @@ to pass bridged IPv4 traffic to iptables' chains. This is a requirement for some please see [here](https://kubernetes.io/docs/concepts/cluster-administration/network-plugins/#network-plugin-requirements). ```shell -kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/v0.9.0/Documentation/kube-flannel.yml +kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/v0.9.1/Documentation/kube-flannel.yml ``` {% endcapture %} From f4b9cf45818b18460f045d6dc70b89f0855e3c7b Mon Sep 17 00:00:00 2001 From: Gabriel Silva Vinha Date: Thu, 16 Nov 2017 16:01:43 -0300 Subject: [PATCH 26/53] Add direction and protocol for kubeadm ports setup (#6319) --- docs/setup/independent/install-kubeadm.md | 26 +++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/setup/independent/install-kubeadm.md b/docs/setup/independent/install-kubeadm.md index a85fbd1f43..3a4c1536c2 100644 --- a/docs/setup/independent/install-kubeadm.md +++ b/docs/setup/independent/install-kubeadm.md @@ -40,22 +40,22 @@ If you have more than one network adapter, and your Kubernetes components are no ### Master node(s) -| Port Range | Purpose | -|------------|---------------------------------| -| 6443* | Kubernetes API server | -| 2379-2380 | etcd server client API | -| 10250 | Kubelet API | -| 10251 | kube-scheduler | -| 10252 | kube-controller-manager | -| 10255 | Read-only Kubelet API (Heapster)| +| Protocol | Direction | Port Range | Purpose | +|----------|-----------|------------|---------------------------------| +| TCP | Inbound | 6443* | Kubernetes API server | +| TCP | Inbound | 2379-2380 | etcd server client API | +| TCP | Inbound | 10250 | Kubelet API | +| TCP | Inbound | 10251 | kube-scheduler | +| TCP | Inbound | 10252 | kube-controller-manager | +| TCP | Inbound | 10255 | Read-only Kubelet API (Heapster)| ### Worker node(s) -| Port Range | Purpose | -|-------------|---------------------------------| -| 10250 | Kubelet API | -| 10255 | Read-only Kubelet API (Heapster)| -| 30000-32767 | Default port range for [NodePort Services](/docs/concepts/services-networking/service/). Typically, these ports would need to be exposed to external load-balancers, or other external consumers of the application itself. | +| Protocol | Direction | Port Range | Purpose | +|----------|-----------|-------------|---------------------------------| +| TCP | Inbound | 10250 | Kubelet API | +| TCP | Inbound | 10255 | Read-only Kubelet API (Heapster)| +| TCP | Inbound | 30000-32767 | Default port range for [NodePort Services](/docs/concepts/services-networking/service/). Typically, these ports would need to be exposed to external load-balancers, or other external consumers of the application itself. | Any port numbers marked with * are overridable, so you will need to ensure any custom ports you provide are also open. From 7f84d9a87330daa347fc76b4b8822a57630ad72c Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Fri, 17 Nov 2017 03:11:21 +0800 Subject: [PATCH 27/53] Update access-cluster.md (#6332) Update format. --- .../access-cluster.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/tasks/access-application-cluster/access-cluster.md b/docs/tasks/access-application-cluster/access-cluster.md index 29e6e08393..0ae68442b5 100644 --- a/docs/tasks/access-application-cluster/access-cluster.md +++ b/docs/tasks/access-application-cluster/access-cluster.md @@ -293,14 +293,17 @@ The redirect capabilities have been deprecated and removed. Please use a proxy There are several different proxies you may encounter when using Kubernetes: - 1. The [kubectl proxy](#directly-accessing-the-rest-api): +1. The [kubectl proxy](#directly-accessing-the-rest-api): + - runs on a user's desktop or in a pod - proxies from a localhost address to the Kubernetes apiserver - client to proxy uses HTTP - proxy to apiserver uses HTTPS - locates apiserver - adds authentication headers - 1. The [apiserver proxy](#discovering-builtin-services): + +1. The [apiserver proxy](#discovering-builtin-services): + - is a bastion built into the apiserver - connects a user outside of the cluster to cluster IPs which otherwise might not be reachable - runs in the apiserver processes @@ -308,17 +311,23 @@ There are several different proxies you may encounter when using Kubernetes: - proxy to target may use HTTP or HTTPS as chosen by proxy using available information - can be used to reach a Node, Pod, or Service - does load balancing when used to reach a Service - 1. The [kube proxy](/docs/concepts/services-networking/service/#ips-and-vips): + +1. The [kube proxy](/docs/concepts/services-networking/service/#ips-and-vips): + - runs on each node - proxies UDP and TCP - does not understand HTTP - provides load balancing - is just used to reach services - 1. A Proxy/Load-balancer in front of apiserver(s): + +1. A Proxy/Load-balancer in front of apiserver(s): + - existence and implementation varies from cluster to cluster (e.g. nginx) - sits between all clients and one or more apiservers - acts as load balancer if there are several apiservers. - 1. Cloud Load Balancers on external services: + +1. Cloud Load Balancers on external services: + - are provided by some cloud providers (e.g. AWS ELB, Google Cloud Load Balancer) - are created automatically when the Kubernetes service has type `LoadBalancer` - use UDP/TCP only From 87ae813ec5e217fce0a8dc7d8c6a8fed65693d89 Mon Sep 17 00:00:00 2001 From: Min RK Date: Thu, 16 Nov 2017 21:58:22 +0100 Subject: [PATCH 28/53] remove period from section title (#6354) to be consistent with sibling titles --- docs/concepts/services-networking/network-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/services-networking/network-policies.md b/docs/concepts/services-networking/network-policies.md index 281a568639..addcd89710 100644 --- a/docs/concepts/services-networking/network-policies.md +++ b/docs/concepts/services-networking/network-policies.md @@ -127,7 +127,7 @@ spec: - {} ``` -### Default deny all egress traffic. +### Default deny all egress traffic You can create a "default" egress isolation policy for a namespace by creating a NetworkPolicy that selects all pods but does not allow any egress traffic from those pods. From 9812e6954dcc8d215c2999390abd17d79fa159f4 Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Fri, 17 Nov 2017 09:34:46 +0800 Subject: [PATCH 29/53] Update cluster-large.md delete addtion `/` in url link. --- docs/admin/cluster-large.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/cluster-large.md b/docs/admin/cluster-large.md index fea0cb9d46..b443d42132 100644 --- a/docs/admin/cluster-large.md +++ b/docs/admin/cluster-large.md @@ -100,7 +100,7 @@ To avoid running into cluster addon resource issues, when creating a cluster wit * Scale memory and CPU limits for each of the following addons, if used, as you scale up the size of cluster (there is one replica of each handling the entire cluster so memory and CPU usage tends to grow proportionally with size/load on cluster): * [InfluxDB and Grafana](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/cluster-monitoring/influxdb/influxdb-grafana-controller.yaml) * [kubedns, dnsmasq, and sidecar](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/dns/kube-dns.yaml.in) - * [Kibana](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons//fluentd-elasticsearch/kibana-deployment.yaml) + * [Kibana](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/fluentd-elasticsearch/kibana-deployment.yaml) * Scale number of replicas for the following addons, if used, along with the size of cluster (there are multiple replicas of each so increasing replicas should help handle increased load, but, since load per replica also increases slightly, also consider increasing CPU/memory limits): * [elasticsearch](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/fluentd-elasticsearch/es-statefulset.yaml) * Increase memory and CPU limits slightly for each of the following addons, if used, along with the size of cluster (there is one replica per node but CPU/memory usage increases slightly along with cluster load/size as well): From 0a79ed9a158ddc5e75d30d124b50871de2902a80 Mon Sep 17 00:00:00 2001 From: stewart-yu Date: Fri, 17 Nov 2017 10:23:45 +0800 Subject: [PATCH 30/53] fix deadlink --- cn/docs/tasks/administer-cluster/cpu-memory-limit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn/docs/tasks/administer-cluster/cpu-memory-limit.md b/cn/docs/tasks/administer-cluster/cpu-memory-limit.md index b2c8e625d6..b437c8a2f0 100644 --- a/cn/docs/tasks/administer-cluster/cpu-memory-limit.md +++ b/cn/docs/tasks/administer-cluster/cpu-memory-limit.md @@ -250,7 +250,7 @@ default Active 12m {% capture whatsnext %} -* 查看 [LimitRange 设计文档](https://git.k8s.io/community/contributors/design-proposals/admission_control_limit_range.md) 获取更多信息。 +* 查看 [LimitRange 设计文档](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/resource-management/admission_control_limit_range.md) 获取更多信息。 * 查看 [资源](/docs/concepts/configuration/manage-compute-resources-container/) 获取关于 Kubernetes 资源模型的详细描述。 {% endcapture %} From 5e19e823b5f9f568e62410b8fdea48df902c6e77 Mon Sep 17 00:00:00 2001 From: Qiming Date: Fri, 17 Nov 2017 10:45:35 +0800 Subject: [PATCH 31/53] Split persistent volume concept article (#6215) --- _data/concepts.yml | 1 + _includes/default-storage-class-prereqs.md | 2 +- docs/concepts/storage/persistent-volumes.md | 541 ++--------------- docs/concepts/storage/storage-classes.md | 636 ++++++++++++++++++++ 4 files changed, 687 insertions(+), 493 deletions(-) create mode 100644 docs/concepts/storage/storage-classes.md diff --git a/_data/concepts.yml b/_data/concepts.yml index 6035a3edcd..8eaab9e39e 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -84,6 +84,7 @@ toc: section: - docs/concepts/storage/volumes.md - docs/concepts/storage/persistent-volumes.md + - docs/concepts/storage/storage-classes.md - docs/concepts/storage/dynamic-provisioning.md - title: Cluster Administration diff --git a/_includes/default-storage-class-prereqs.md b/_includes/default-storage-class-prereqs.md index a4747d9032..ef4823318d 100644 --- a/_includes/default-storage-class-prereqs.md +++ b/_includes/default-storage-class-prereqs.md @@ -1,5 +1,5 @@ You need to either have a dynamic PersistentVolume provisioner with a default -[StorageClass](/docs/user-guide/persistent-volumes/#storageclasses), +[StorageClass](/docs/concepts/storage/storage-classes/), or [statically provision PersistentVolumes](/docs/user-guide/persistent-volumes/#provisioning) yourself to satisfy the [PersistentVolumeClaims](/docs/user-guide/persistent-volumes/#persistentvolumeclaims) used here. diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md index f1eb6c971f..608a5bcda9 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/docs/concepts/storage/persistent-volumes.md @@ -28,13 +28,6 @@ ways than just size and access modes, without exposing users to the details of how those volumes are implemented. For these needs there is the `StorageClass` resource. -A `StorageClass` provides a way for administrators to describe the "classes" of -storage they offer. Different classes might map to quality-of-service levels, -or to backup policies, or to arbitrary policies determined by the cluster -administrators. Kubernetes itself is unopinionated about what classes -represent. This concept is sometimes called "profiles" in other storage -systems. - Please see the [detailed walkthrough with working examples](/docs/tasks/configure-pod-container/configure-persistent-volume-storage/). @@ -52,7 +45,8 @@ A cluster administrator creates a number of PVs. They carry the details of the r #### Dynamic When none of the static PVs the administrator created matches a user's `PersistentVolumeClaim`, the cluster may try to dynamically provision a volume specially for the PVC. -This provisioning is based on `StorageClasses`: the PVC must request a class and +This provisioning is based on `StorageClasses`: the PVC must request a +[storage class](/docs/concepts/storage/storage-classes/) and the administrator must have created and configured that class in order for dynamic provisioning to occur. Claims that request the class `""` effectively disable dynamic provisioning for themselves. @@ -255,7 +249,8 @@ In the CLI, the access modes are abbreviated to: A PV can have a class, which is specified by setting the `storageClassName` attribute to the name of a -`StorageClass`. A PV of a particular class can only be bound to PVCs requesting +[StorageClass](/docs/concepts/storage/storage-classes/). +A PV of a particular class can only be bound to PVCs requesting that class. A PV with no `storageClassName` has no class and can only be bound to PVCs that request no particular class. @@ -356,7 +351,8 @@ All of the requirements, from both `matchLabels` and `matchExpressions` are ANDe ### Class A claim can request a particular class by specifying the name of a -`StorageClass` using the attribute `storageClassName`. +[StorageClass](/docs/concepts/storage/storage-classes/) +using the attribute `storageClassName`. Only PVs of the requested class, ones with the same `storageClassName` as the PVC, can be bound to the PVC. @@ -369,17 +365,17 @@ by the cluster depending on whether the is turned on. * If the admission plugin is turned on, the administrator may specify a -default `StorageClass`. All PVCs that have no `storageClassName` can be bound only to -PVs of that default. Specifying a default `StorageClass` is done by setting the -annotation `storageclass.kubernetes.io/is-default-class` equal to "true" in -a `StorageClass` object. If the administrator does not specify a default, the -cluster responds to PVC creation as if the admission plugin were turned off. If -more than one default is specified, the admission plugin forbids the creation of -all PVCs. + default `StorageClass`. All PVCs that have no `storageClassName` can be bound only to + PVs of that default. Specifying a default `StorageClass` is done by setting the + annotation `storageclass.kubernetes.io/is-default-class` equal to "true" in + a `StorageClass` object. If the administrator does not specify a default, the + cluster responds to PVC creation as if the admission plugin were turned off. If + more than one default is specified, the admission plugin forbids the creation of + all PVCs. * If the admission plugin is turned off, there is no notion of a default -`StorageClass`. All PVCs that have no `storageClassName` can be bound only to PVs that -have no class. In this case, the PVCs that have no `storageClassName` are treated the -same way as PVCs that have their `storageClassName` set to `""`. + `StorageClass`. All PVCs that have no `storageClassName` can be bound only to PVs that + have no class. In this case, the PVCs that have no `storageClassName` are treated the + same way as PVCs that have their `storageClassName` set to `""`. Depending on installation method, a default StorageClass may be deployed to Kubernetes cluster by addon manager during installation. @@ -421,481 +417,42 @@ spec: `PersistentVolumes` binds are exclusive, and since `PersistentVolumeClaims` are namespaced objects, mounting claims with "Many" modes (`ROX`, `RWX`) is only possible within one namespace. -## StorageClasses - -Each `StorageClass` contains the fields `provisioner`, `parameters`, and -`reclaimPolicy`, which are used when a `PersistentVolume` belonging to the -class needs to be dynamically provisioned. - -The name of a `StorageClass` object is significant, and is how users can -request a particular class. Administrators set the name and other parameters -of a class when first creating `StorageClass` objects, and the objects cannot -be updated once they are created. - -Administrators can specify a default `StorageClass` just for PVCs that don't -request any particular class to bind to: see the -[`PersistentVolumeClaim` section](#persistentvolumeclaims) -for details. - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: standard -provisioner: kubernetes.io/aws-ebs -parameters: - type: gp2 -reclaimPolicy: Retain -mountOptions: - - debug -``` - -### Provisioner -Storage classes have a provisioner that determines what volume plugin is used -for provisioning PVs. This field must be specified. - -| Volume Plugin | Internal Provisioner| Config Example | -| :--- | :---: | :---: | -| AWSElasticBlockStore | ✓ | [AWS](#aws) | -| AzureFile | ✓ | [Azure File](#azure-file) | -| AzureDisk | ✓ | [Azure Disk](#azure-disk) | -| CephFS | - | - | -| Cinder | ✓ | [OpenStack Cinder](#openstack-cinder)| -| FC | - | - | -| FlexVolume | - | - | -| Flocker | ✓ | - | -| GCEPersistentDisk | ✓ | [GCE](#gce) | -| Glusterfs | ✓ | [Glusterfs](#glusterfs) | -| iSCSI | - | - | -| PhotonPersistentDisk | ✓ | - | -| Quobyte | ✓ | [Quobyte](#quobyte) | -| NFS | - | - | -| RBD | ✓ | [Ceph RBD](#ceph-rbd) | -| VsphereVolume | ✓ | [vSphere](#vsphere) | -| PortworxVolume | ✓ | [Portworx Volume](#portworx-volume) | -| ScaleIO | ✓ | [ScaleIO](#scaleio) | -| StorageOS | ✓ | [StorageOS](#storageos) | - -You are not restricted to specifying the "internal" provisioners -listed here (whose names are prefixed with "kubernetes.io" and shipped -alongside Kubernetes). You can also run and specify external provisioners, -which are independent programs that follow a [specification](https://git.k8s.io/community/contributors/design-proposals/storage/volume-provisioning.md) -defined by Kubernetes. Authors of external provisioners have full discretion -over where their code lives, how the provisioner is shipped, how it needs to be -run, what volume plugin it uses (including Flex), etc. The repository [kubernetes-incubator/external-storage](https://github.com/kubernetes-incubator/external-storage) -houses a library for writing external provisioners that implements the bulk of -the specification plus various community-maintained external provisioners. - -For example, NFS doesn't provide an internal provisioner, but an external provisioner -can be used. Some external provisioners are listed under the repository [kubernetes-incubator/external-storage](https://github.com/kubernetes-incubator/external-storage). -There are also cases when 3rd party storage vendors provide their own external -provisioner. - -### Reclaim Policy -Persistent Volumes that are dynamically created by a storage class will have the -reclaim policy specified in the `reclaimPolicy` field of the class, which can be -either `Delete` or `Retain`. If no `reclaimPolicy` is specified when a -`StorageClass` object is created, it will default to `Delete`. - -Persistent Volumes that are created manually and managed via a storage class will have -whatever reclaim policy they were assigned at creation. - -### Mount Options -Persistent Volumes that are dynamically created by a storage class will have the -mount options specified in the `mountOptions` field of the class. - -If the volume plugin does not support mount options but mount options are -specified, provisioning will fail. Mount options are not validated on neither -the class nor PV, so mount of the PV will simply fail if one is invalid. - -### Parameters -Storage classes have parameters that describe volumes belonging to the storage -class. Different parameters may be accepted depending on the `provisioner`. For - example, the value `io1`, for the parameter `type`, and the parameter -`iopsPerGB` are specific to EBS. When a parameter is omitted, some default is -used. - -#### AWS - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: slow -provisioner: kubernetes.io/aws-ebs -parameters: - type: io1 - zones: us-east-1d, us-east-1c - iopsPerGB: "10" -``` - -* `type`: `io1`, `gp2`, `sc1`, `st1`. See [AWS docs](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html) for details. Default: `gp2`. -* `zone`: AWS zone. If neither `zone` nor `zones` is specified, volumes are generally round-robin-ed across all active zones where Kubernetes cluster has a node. `zone` and `zones` parameters must not be used at the same time. -* `zones`: A comma separated list of AWS zone(s). If neither `zone` nor `zones` is specified, volumes are generally round-robin-ed across all active zones where Kubernetes cluster has a node. `zone` and `zones` parameters must not be used at the same time. -* `iopsPerGB`: only for `io1` volumes. I/O operations per second per GiB. AWS volume plugin multiplies this with size of requested volume to compute IOPS of the volume and caps it at 20 000 IOPS (maximum supported by AWS, see [AWS docs](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html). A string is expected here, i.e. `"10"`, not `10`. -* `encrypted`: denotes whether the EBS volume should be encrypted or not. Valid values are `"true"` or `"false"`. A string is expected here, i.e. `"true"`, not `true`. -* `kmsKeyId`: optional. The full Amazon Resource Name of the key to use when encrypting the volume. If none is supplied but `encrypted` is true, a key is generated by AWS. See AWS docs for valid ARN value. - -#### GCE - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: slow -provisioner: kubernetes.io/gce-pd -parameters: - type: pd-standard - zones: us-central1-a, us-central1-b -``` - -* `type`: `pd-standard` or `pd-ssd`. Default: `pd-standard` -* `zone`: GCE zone. If neither `zone` nor `zones` is specified, volumes are generally round-robin-ed across all active zones where Kubernetes cluster has a node. `zone` and `zones` parameters must not be used at the same time. -* `zones`: A comma separated list of GCE zone(s). If neither `zone` nor `zones` is specified, volumes are generally round-robin-ed across all active zones where Kubernetes cluster has a node. `zone` and `zones` parameters must not be used at the same time. - -#### Glusterfs - -```yaml -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: slow -provisioner: kubernetes.io/glusterfs -parameters: - resturl: "http://127.0.0.1:8081" - clusterid: "630372ccdc720a92c681fb928f27b53f" - restauthenabled: "true" - restuser: "admin" - secretNamespace: "default" - secretName: "heketi-secret" - gidMin: "40000" - gidMax: "50000" - volumetype: "replicate:3" -``` - -* `resturl`: Gluster REST service/Heketi service url which provision gluster volumes on demand. The general format should be `IPaddress:Port` and this is a mandatory parameter for GlusterFS dynamic provisioner. If Heketi service is exposed as a routable service in openshift/kubernetes setup, this can have a format similar to -`http://heketi-storage-project.cloudapps.mystorage.com` where the fqdn is a resolvable heketi service url. -* `restauthenabled` : Gluster REST service authentication boolean that enables authentication to the REST server. If this value is 'true', `restuser` and `restuserkey` or `secretNamespace` + `secretName` have to be filled. This option is deprecated, authentication is enabled when any of `restuser`, `restuserkey`, `secretName` or `secretNamespace` is specified. -* `restuser` : Gluster REST service/Heketi user who has access to create volumes in the Gluster Trusted Pool. -* `restuserkey` : Gluster REST service/Heketi user's password which will be used for authentication to the REST server. This parameter is deprecated in favor of `secretNamespace` + `secretName`. -* `secretNamespace`, `secretName` : Identification of Secret instance that contains user password to use when talking to Gluster REST service. These parameters are optional, empty password will be used when both `secretNamespace` and `secretName` are omitted. The provided secret must have type "kubernetes.io/glusterfs", e.g. created in this way: - ``` - $ kubectl create secret generic heketi-secret --type="kubernetes.io/glusterfs" --from-literal=key='opensesame' --namespace=default - ``` - Example of a secret can be found in [glusterfs-provisioning-secret.yaml](https://github.com/kubernetes/examples/tree/master/staging/persistent-volume-provisioning/glusterfs/glusterfs-secret.yaml). -* `clusterid`: `630372ccdc720a92c681fb928f27b53f` is the ID of the cluster which will be used by Heketi when provisioning the volume. It can also be a list of clusterids, for ex: - "8452344e2becec931ece4e33c4674e4e,42982310de6c63381718ccfa6d8cf397". This is an optional parameter. -* `gidMin`, `gidMax` : The minimum and maximum value of GID range for the storage class. A unique value (GID) in this range ( gidMin-gidMax ) will be used for dynamically provisioned volumes. These are optional values. If not specified, the volume will be provisioned with a value between 2000-2147483647 which are defaults for gidMin and gidMax respectively. -* `volumetype` : The volume type and its parameters can be configured with this optional value. If the volume type is not mentioned, it's up to the provisioner to decide the volume type. - For example: - 'Replica volume': - `volumetype: replicate:3` where '3' is replica count. - 'Disperse/EC volume': - `volumetype: disperse:4:2` where '4' is data and '2' is the redundancy count. - 'Distribute volume': - `volumetype: none` - - For available volume types and administration options, refer to the [Administration Guide](https://access.redhat.com/documentation/en-US/Red_Hat_Storage/3.1/html/Administration_Guide/part-Overview.html). - - For further reference information, see [How to configure Heketi](https://github.com/heketi/heketi/wiki/Setting-up-the-topology). - - When persistent volumes are dynamically provisioned, the Gluster plugin automatically creates an endpoint and a headless service in the name `gluster-dynamic-`. The dynamic endpoint and service are automatically deleted when the persistent volume claim is deleted. - -#### OpenStack Cinder - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: gold -provisioner: kubernetes.io/cinder -parameters: - type: fast - availability: nova -``` - -* `type`: [VolumeType](https://docs.openstack.org/user-guide/dashboard-manage-volumes.html) created in Cinder. Default is empty. -* `availability`: Availability Zone. If not specified, volumes are generally round-robin-ed across all active zones where Kubernetes cluster has a node. - -#### vSphere - -1. Create a StorageClass with a user specified disk format. - - kind: StorageClass - apiVersion: storage.k8s.io/v1 - metadata: - name: fast - provisioner: kubernetes.io/vsphere-volume - parameters: - diskformat: zeroedthick - - `diskformat`: `thin`, `zeroedthick` and `eagerzeroedthick`. Default: `"thin"`. - -2. Create a StorageClass with a disk format on a user specified datastore. - - kind: StorageClass - apiVersion: storage.k8s.io/v1 - metadata: - name: fast - provisioner: kubernetes.io/vsphere-volume - parameters: - diskformat: zeroedthick - datastore: VSANDatastore - - `datastore`: The user can also specify the datastore in the StorageClass. The volume will be created on the datastore specified in the storage class, which in this case is `VSANDatastore`. This field is optional. If the datastore is not specified, then the volume will be created on the datastore specified in the vSphere config file used to initialize the vSphere Cloud Provider. - -3. Storage Policy Management inside kubernetes - - * Using existing vCenter SPBM policy - - One of the most important features of vSphere for Storage Management is policy based Management. Storage Policy Based Management (SPBM) is a storage policy framework that provides a single unified control plane across a broad range of data services and storage solutions. SPBM enables vSphere administrators to overcome upfront storage provisioning challenges, such as capacity planning, differentiated service levels and managing capacity headroom. - - The SPBM policies can be specified in the StorageClass using the storagePolicyName parameter. - - * Virtual SAN policy support inside Kubernetes - - Vsphere Infrastructure (VI) Admins will have the ability to specify custom Virtual SAN Storage Capabilities during dynamic volume provisioning. You can now define storage requirements, such as performance and availability, in the form of storage capabilities during dynamic volume provisioning. The storage capability requirements are converted into a Virtual SAN policy which are then pushed down to the Virtual SAN layer when a persistent volume (virtual disk) is being created. The virtual disk is distributed across the Virtual SAN datastore to meet the requirements. - - You can see [Storage Policy Based Management for dynamic provisioning of volumes](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/policy-based-mgmt.html) for more details on how to use storage policies for persistent volumes management. - -There are few [vSphere examples](https://github.com/kubernetes/examples/tree/master/staging/volumes/vsphere) which you try out for persistent volume management inside Kubernetes for vSphere. - -#### Ceph RBD - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: fast -provisioner: kubernetes.io/rbd -parameters: - monitors: 10.16.153.105:6789 - adminId: kube - adminSecretName: ceph-secret - adminSecretNamespace: kube-system - pool: kube - userId: kube - userSecretName: ceph-secret-user - fsType: ext4 - imageFormat: "2" - imageFeatures: "layering" -``` - -* `monitors`: Ceph monitors, comma delimited. This parameter is required. -* `adminId`: Ceph client ID that is capable of creating images in the pool. Default is "admin". -* `adminSecretNamespace`: The namespace for `adminSecret`. Default is "default". -* `adminSecret`: Secret Name for `adminId`. This parameter is required. The provided secret must have type "kubernetes.io/rbd". -* `pool`: Ceph RBD pool. Default is "rbd". -* `userId`: Ceph client ID that is used to map the RBD image. Default is the same as `adminId`. -* `userSecretName`: The name of Ceph Secret for `userId` to map RBD image. It must exist in the same namespace as PVCs. This parameter is required. The provided secret must have type "kubernetes.io/rbd", e.g. created in this way: - ``` - $ kubectl create secret generic ceph-secret --type="kubernetes.io/rbd" --from-literal=key='QVFEQ1pMdFhPUnQrSmhBQUFYaERWNHJsZ3BsMmNjcDR6RFZST0E9PQ==' --namespace=kube-system - ``` -* `fsType`: fsType that is supported by kubernetes. Default: `"ext4"`. -* `imageFormat`: Ceph RBD image format, "1" or "2". Default is "1". -* `imageFeatures`: This parameter is optional and should only be used if you set `imageFormat` to "2". Currently supported features are `layering` only. Default is "", and no features are turned on. - -#### Quobyte - -```yaml -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: slow -provisioner: kubernetes.io/quobyte -parameters: - quobyteAPIServer: "http://138.68.74.142:7860" - registry: "138.68.74.142:7861" - adminSecretName: "quobyte-admin-secret" - adminSecretNamespace: "kube-system" - user: "root" - group: "root" - quobyteConfig: "BASE" - quobyteTenant: "DEFAULT" -``` - -* `quobyteAPIServer`: API Server of Quobyte in the format `http(s)://api-server:7860` -* `registry`: Quobyte registry to use to mount the volume. You can specify the registry as ``:`` pair or if you want to specify multiple registries you just have to put a comma between them e.q. ``:,:,:``. The host can be an IP address or if you have a working DNS you can also provide the DNS names. -* `adminSecretNamespace`: The namespace for `adminSecretName`. Default is "default". -* `adminSecretName`: secret that holds information about the Quobyte user and the password to authenticate against the API server. The provided secret must have type "kubernetes.io/quobyte", e.g. created in this way: - ``` - $ kubectl create secret generic quobyte-admin-secret --type="kubernetes.io/quobyte" --from-literal=key='opensesame' --namespace=kube-system - ``` -* `user`: maps all access to this user. Default is "root". -* `group`: maps all access to this group. Default is "nfsnobody". -* `quobyteConfig`: use the specified configuration to create the volume. You can create a new configuration or modify an existing one with the Web console or the quobyte CLI. Default is "BASE". -* `quobyteTenant`: use the specified tenant ID to create/delete the volume. This Quobyte tenant has to be already present in Quobyte. Default is "DEFAULT". - -#### Azure Disk - -##### Azure Unmanaged Disk Storage Class - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: slow -provisioner: kubernetes.io/azure-disk -parameters: - skuName: Standard_LRS - location: eastus - storageAccount: azure_storage_account_name -``` - -* `skuName`: Azure storage account Sku tier. Default is empty. -* `location`: Azure storage account location. Default is empty. -* `storageAccount`: Azure storage account name. If a storage account is provided, it must reside in the same resource group as the cluster, and `location` is ignored. If a storage account is not provided, a new storage account will be created in the same resource group as the cluster. - -##### New Azure Disk Storage Class (starting from v1.7.2) - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: slow -provisioner: kubernetes.io/azure-disk -parameters: - storageaccounttype: Standard_LRS - kind: Shared -``` - -* `storageaccounttype`: Azure storage account Sku tier. Default is empty. -* `kind`: Possible values are `shared` (default), `dedicated`, and `managed`. When `kind` is `shared`, all unmanaged disks are created in a few shared storage accounts in the same resource group as the cluster. When `kind` is `dedicated`, a new dedicated storage account will be created for the new unmanaged disk in the same resource group as the cluster. - -- Premium VM can attach both Standard_LRS and Premium_LRS disks, while Standard VM can only attach Standard_LRS disks. -- Managed VM can only attach managed disks and unmanaged VM can only attach unmanaged disks. - -#### Azure File - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: azurefile -provisioner: kubernetes.io/azure-file -parameters: - skuName: Standard_LRS - location: eastus - storageAccount: azure_storage_account_name -``` - -* `skuName`: Azure storage account Sku tier. Default is empty. -* `location`: Azure storage account location. Default is empty. -* `storageAccount`: Azure storage account name. Default is empty. If a storage account is not provided, all storage accounts associated with the resource group are searched to find one that matches `skuName` and `location`. If a storage account is provided, it must reside in the same resource group as the cluster, and `skuName` and `location` are ignored. - -During provision, a secret is created for mounting credentials. If the cluster has enabled both [RBAC](/docs/admin/authorization/rbac/) and [Controller Roles](/docs/admin/authorization/rbac/#controller-roles), add the `create` permission of resource `secret` for clusterrole `system:controller:persistent-volume-binder`. - -#### Portworx Volume - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: portworx-io-priority-high -provisioner: kubernetes.io/portworx-volume -parameters: - repl: "1" - snap_interval: "70" - io_priority: "high" - -``` - -* `fs`: filesystem to be laid out: [none/xfs/ext4] (default: `ext4`). -* `block_size`: block size in Kbytes (default: `32`). -* `repl`: number of synchronous replicas to be provided in the form of replication factor [1..3] (default: `1`) A string is expected here i.e.`"1"` and not `1`. -* `io_priority`: determines whether the volume will be created from higher performance or a lower priority storage [high/medium/low] (default: `low`). -* `snap_interval`: clock/time interval in minutes for when to trigger snapshots. Snapshots are incremental based on difference with the prior snapshot, 0 disables snaps (default: `0`). A string is expected here i.e. `"70"` and not `70`. -* `aggregation_level`: specifies the number of chunks the volume would be distributed into, 0 indicates a non-aggregated volume (default: `0`). A string is expected here i.e. `"0"` and not `0` -* `ephemeral`: specifies whether the volume should be cleaned-up after unmount or should be persistent. `emptyDir` use case can set this value to true and `persistent volumes` use case such as for databases like Cassandra should set to false, [true/false] (default `false`). A string is expected here i.e. `"true"` and not `true`. - -#### ScaleIO - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: slow -provisioner: kubernetes.io/scaleio -parameters: - gateway: https://192.168.99.200:443/api - system: scaleio - protectionDomain: pd0 - storagePool: sp1 - storageMode: ThinProvisioned - secretRef: sio-secret - readOnly: false - fsType: xfs -``` - -* `provisioner`: attribute is set to `kubernetes.io/scaleio` -* `gateway`: address to a ScaleIO API gateway (required) -* `system`: the name of the ScaleIO system (required) -* `protectionDomain`: the name of the ScaleIO protection domain (required) -* `storagePool`: the name of the volume storage pool (required) -* `storageMode`: the storage provision mode: `ThinProvisioned` (default) or `ThickProvisioned` -* `secretRef`: reference to a configured Secret object (required) -* `readOnly`: specifies the access mode to the mounted volume (default false) -* `fsType`: the file system to use for the volume (default ext4) - -The ScaleIO Kubernetes volume plugin requires a configured Secret object. -The secret must be created with type `kubernetes.io/scaleio` and use the same namespace value as that of the PVC where it is referenced -as shown in the following command: - -``` -$> kubectl create secret generic sio-secret --type="kubernetes.io/scaleio" --from-literal=username=sioadmin --from-literal=password=d2NABDNjMA== --namespace=default -``` - -#### StorageOS - -```yaml -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: fast -provisioner: kubernetes.io/storageos -parameters: - pool: default - description: Kubernetes volume - fsType: ext4 - adminSecretNamespace: default - adminSecretName: storageos-secret -``` - -* `pool`: The name of the StorageOS distributed capacity pool to provision the volume from. Uses the `default` pool which is normally present if not specified. -* `description`: The description to assign to volumes that were created dynamically. All volume descriptions will be the same for the storage class, but different storage classes can be used to allow descriptions for different use cases. Defaults to `Kubernetes volume`. -* `fsType`: The default filesystem type to request. Note that user-defined rules within StorageOS may override this value. Defaults to `ext4`. -* `adminSecretNamespace`: The namespace where the API configuration secret is located. Required if adminSecretName set. -* `adminSecretName`: The name of the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -The StorageOS Kubernetes volume plugin can use a Secret object to specify an endpoint and credentials to access the StorageOS API. This is only required when the defaults have been changed. -The secret must be created with type `kubernetes.io/storageos` as shown in the following command: - -``` -$ kubectl create secret generic storageos-secret --type="kubernetes.io/storageos" --from-literal=apiAddress=tcp://localhost:5705 --from-literal=apiUsername=storageos --from-literal=apiPassword=storageos --namespace=default -``` - -Secrets used for dynamically provisioned volumes may be created in any namespace and referenced with the `adminSecretNamespace` parameter. Secrets used by pre-provisioned volumes must be created in the same namespace as the PVC that references it. +`` ## Writing Portable Configuration If you're writing configuration templates or examples that run on a wide range of clusters and need persistent storage, we recommend that you use the following pattern: -- Do include PersistentVolumeClaim objects in your bundle of config (alongside Deployments, ConfigMaps, etc). -- Do not include PersistentVolume objects in the config, since the user instantiating the config may not have - permission to create PersistentVolumes. -- Give the user the option of providing a storage class name when instantiating the template. - - If the user provides a storage class name, and the cluster is version 1.4 or newer, put that value into the `volume.beta.kubernetes.io/storage-class` annotation of the PVC. - This will cause the PVC to match the right storage class if the cluster has StorageClasses enabled by the admin. - - If the user does not provide a storage class name or the cluster is version 1.3, then instead put a `volume.alpha.kubernetes.io/storage-class: default` annotation on the PVC. - - This will cause a PV to be automatically provisioned for the user with sane default characteristics on some clusters. - - Despite the word `alpha` in the name, the code behind this annotation has `beta` level support. - - Do not use `volume.beta.kubernetes.io/storage-class:` with any value including the empty string since it will prevent DefaultStorageClass admission controller - from running if enabled. -- In your tooling, do watch for PVCs that are not getting bound after some time and surface this to the user, as this may indicate that the cluster has no dynamic - storage support (in which case the user should create a matching PV) or the cluster has no storage system (in which case the user cannot deploy config requiring - PVCs). -- In the future, we expect most clusters to have `DefaultStorageClass` enabled, and to have some form of storage available. However, there may not be any - storage class names which work on all clusters, so continue to not set one by default. - At some point, the alpha annotation will cease to have meaning, but the unset `storageClass` field on the PVC - will have the desired effect. +- Do include PersistentVolumeClaim objects in your bundle of config (alongside + Deployments, ConfigMaps, etc). +- Do not include PersistentVolume objects in the config, since the user instantiating + the config may not have permission to create PersistentVolumes. +- Give the user the option of providing a storage class name when instantiating + the template. + - If the user provides a storage class name, and the cluster is version 1.4 + or newer, put that value into the `volume.beta.kubernetes.io/storage-class` + annotation of the PVC. This will cause the PVC to match the right storage + class if the cluster has StorageClasses enabled by the admin. + - If the user does not provide a storage class name or the cluster is version + 1.3, then instead put a `volume.alpha.kubernetes.io/storage-class: default` + annotation on the PVC. + - This will cause a PV to be automatically provisioned for the user with + sane default characteristics on some clusters. + - Despite the word `alpha` in the name, the code behind this annotation has + `beta` level support. + - Do not use `volume.beta.kubernetes.io/storage-class:` with any value + including the empty string since it will prevent `DefaultStorageClass` + admission controller from running if enabled. +- In your tooling, do watch for PVCs that are not getting bound after some time + and surface this to the user, as this may indicate that the cluster has no + dynamic storage support (in which case the user should create a matching PV) + or the cluster has no storage system (in which case the user cannot deploy + config requiring PVCs). +- In the future, we expect most clusters to have `DefaultStorageClass` enabled, + and to have some form of storage available. However, there may not be any + storage class names which work on all clusters, so continue to not set one by + default. + At some point, the alpha annotation will cease to have meaning, but the unset + `storageClass` field on the PVC will have the desired effect. + diff --git a/docs/concepts/storage/storage-classes.md b/docs/concepts/storage/storage-classes.md new file mode 100644 index 0000000000..1aa8ed31e8 --- /dev/null +++ b/docs/concepts/storage/storage-classes.md @@ -0,0 +1,636 @@ +--- +approvers: +- jsafrane +- mikedanese +- saad-ali +- thockin +title: Storage Classes +--- + +This document describes the concept of `StorageClass` in Kubernetes. Familiarity +with [volumes](/docs/concepts/storage/volumes/) and +[persistent volumes](/docs/concepts/storage/persistent-volumes) is suggested. + +* TOC +{:toc} + +## Introduction + +A `StorageClass` provides a way for administrators to describe the "classes" of +storage they offer. Different classes might map to quality-of-service levels, +or to backup policies, or to arbitrary policies determined by the cluster +administrators. Kubernetes itself is unopinionated about what classes +represent. This concept is sometimes called "profiles" in other storage +systems. + +## The StorageClass Resource + +Each `StorageClass` contains the fields `provisioner`, `parameters`, and +`reclaimPolicy`, which are used when a `PersistentVolume` belonging to the +class needs to be dynamically provisioned. + +The name of a `StorageClass` object is significant, and is how users can +request a particular class. Administrators set the name and other parameters +of a class when first creating `StorageClass` objects, and the objects cannot +be updated once they are created. + +Administrators can specify a default `StorageClass` just for PVCs that don't +request any particular class to bind to: see the +[`PersistentVolumeClaim` section](#persistentvolumeclaims) +for details. + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: standard +provisioner: kubernetes.io/aws-ebs +parameters: + type: gp2 +reclaimPolicy: Retain +mountOptions: + - debug +``` + +### Provisioner + +Storage classes have a provisioner that determines what volume plugin is used +for provisioning PVs. This field must be specified. + +| Volume Plugin | Internal Provisioner| Config Example | +| :--- | :---: | :---: | +| AWSElasticBlockStore | ✓ | [AWS](#aws) | +| AzureFile | ✓ | [Azure File](#azure-file) | +| AzureDisk | ✓ | [Azure Disk](#azure-disk) | +| CephFS | - | - | +| Cinder | ✓ | [OpenStack Cinder](#openstack-cinder)| +| FC | - | - | +| FlexVolume | - | - | +| Flocker | ✓ | - | +| GCEPersistentDisk | ✓ | [GCE](#gce) | +| Glusterfs | ✓ | [Glusterfs](#glusterfs) | +| iSCSI | - | - | +| PhotonPersistentDisk | ✓ | - | +| Quobyte | ✓ | [Quobyte](#quobyte) | +| NFS | - | - | +| RBD | ✓ | [Ceph RBD](#ceph-rbd) | +| VsphereVolume | ✓ | [vSphere](#vsphere) | +| PortworxVolume | ✓ | [Portworx Volume](#portworx-volume) | +| ScaleIO | ✓ | [ScaleIO](#scaleio) | +| StorageOS | ✓ | [StorageOS](#storageos) | + +You are not restricted to specifying the "internal" provisioners +listed here (whose names are prefixed with "kubernetes.io" and shipped +alongside Kubernetes). You can also run and specify external provisioners, +which are independent programs that follow a [specification](https://git.k8s.io/community/contributors/design-proposals/storage/volume-provisioning.md) +defined by Kubernetes. Authors of external provisioners have full discretion +over where their code lives, how the provisioner is shipped, how it needs to be +run, what volume plugin it uses (including Flex), etc. The repository [kubernetes-incubator/external-storage](https://github.com/kubernetes-incubator/external-storage) +houses a library for writing external provisioners that implements the bulk of +the specification plus various community-maintained external provisioners. + +For example, NFS doesn't provide an internal provisioner, but an external provisioner +can be used. Some external provisioners are listed under the repository [kubernetes-incubator/external-storage](https://github.com/kubernetes-incubator/external-storage). +There are also cases when 3rd party storage vendors provide their own external +provisioner. + +### Reclaim Policy + +Persistent Volumes that are dynamically created by a storage class will have the +reclaim policy specified in the `reclaimPolicy` field of the class, which can be +either `Delete` or `Retain`. If no `reclaimPolicy` is specified when a +`StorageClass` object is created, it will default to `Delete`. + +Persistent Volumes that are created manually and managed via a storage class will have +whatever reclaim policy they were assigned at creation. + +### Mount Options + +Persistent Volumes that are dynamically created by a storage class will have the +mount options specified in the `mountOptions` field of the class. + +If the volume plugin does not support mount options but mount options are +specified, provisioning will fail. Mount options are not validated on neither +the class nor PV, so mount of the PV will simply fail if one is invalid. + +## Parameters + +Storage classes have parameters that describe volumes belonging to the storage +class. Different parameters may be accepted depending on the `provisioner`. For + example, the value `io1`, for the parameter `type`, and the parameter +`iopsPerGB` are specific to EBS. When a parameter is omitted, some default is +used. + +### AWS + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: slow +provisioner: kubernetes.io/aws-ebs +parameters: + type: io1 + zones: us-east-1d, us-east-1c + iopsPerGB: "10" +``` + +* `type`: `io1`, `gp2`, `sc1`, `st1`. See + [AWS docs](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html) + for details. Default: `gp2`. +* `zone`: AWS zone. If neither `zone` nor `zones` is specified, volumes are + generally round-robin-ed across all active zones where Kubernetes cluster + has a node. `zone` and `zones` parameters must not be used at the same time. +* `zones`: A comma separated list of AWS zone(s). If neither `zone` nor `zones` + is specified, volumes are generally round-robin-ed across all active zones + where Kubernetes cluster has a node. `zone` and `zones` parameters must not + be used at the same time. +* `iopsPerGB`: only for `io1` volumes. I/O operations per second per GiB. AWS + volume plugin multiplies this with size of requested volume to compute IOPS + of the volume and caps it at 20 000 IOPS (maximum supported by AWS, see + [AWS docs](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html). + A string is expected here, i.e. `"10"`, not `10`. +* `encrypted`: denotes whether the EBS volume should be encrypted or not. + Valid values are `"true"` or `"false"`. A string is expected here, + i.e. `"true"`, not `true`. +* `kmsKeyId`: optional. The full Amazon Resource Name of the key to use when + encrypting the volume. If none is supplied but `encrypted` is true, a key is + generated by AWS. See AWS docs for valid ARN value. + +### GCE + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: slow +provisioner: kubernetes.io/gce-pd +parameters: + type: pd-standard + zones: us-central1-a, us-central1-b +``` + +* `type`: `pd-standard` or `pd-ssd`. Default: `pd-standard` +* `zone`: GCE zone. If neither `zone` nor `zones` is specified, volumes are + generally round-robin-ed across all active zones where Kubernetes cluster has + a node. `zone` and `zones` parameters must not be used at the same time. +* `zones`: A comma separated list of GCE zone(s). If neither `zone` nor `zones` + is specified, volumes are generally round-robin-ed across all active zones + where Kubernetes cluster has a node. `zone` and `zones` parameters must not + be used at the same time. + +### Glusterfs + +```yaml +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: slow +provisioner: kubernetes.io/glusterfs +parameters: + resturl: "http://127.0.0.1:8081" + clusterid: "630372ccdc720a92c681fb928f27b53f" + restauthenabled: "true" + restuser: "admin" + secretNamespace: "default" + secretName: "heketi-secret" + gidMin: "40000" + gidMax: "50000" + volumetype: "replicate:3" +``` + +* `resturl`: Gluster REST service/Heketi service url which provision gluster + volumes on demand. The general format should be `IPaddress:Port` and this is + a mandatory parameter for GlusterFS dynamic provisioner. If Heketi service is + exposed as a routable service in openshift/kubernetes setup, this can have a + format similar to `http://heketi-storage-project.cloudapps.mystorage.com` + where the fqdn is a resolvable heketi service url. +* `restauthenabled` : Gluster REST service authentication boolean that enables + authentication to the REST server. If this value is 'true', `restuser` and + `restuserkey` or `secretNamespace` + `secretName` have to be filled. This + option is deprecated, authentication is enabled when any of `restuser`, + `restuserkey`, `secretName` or `secretNamespace` is specified. +* `restuser` : Gluster REST service/Heketi user who has access to create volumes + in the Gluster Trusted Pool. +* `restuserkey` : Gluster REST service/Heketi user's password which will be used + for authentication to the REST server. This parameter is deprecated in favor + of `secretNamespace` + `secretName`. +* `secretNamespace`, `secretName` : Identification of Secret instance that + contains user password to use when talking to Gluster REST service. These + parameters are optional, empty password will be used when both + `secretNamespace` and `secretName` are omitted. The provided secret must have + type "kubernetes.io/glusterfs", e.g. created in this way: + ``` + $ kubectl create secret generic heketi-secret \ + --type="kubernetes.io/glusterfs" --from-literal=key='opensesame' \ + --namespace=default + ``` + Example of a secret can be found in + [glusterfs-provisioning-secret.yaml](https://github.com/kubernetes/examples/tree/master/staging/persistent-volume-provisioning/glusterfs/glusterfs-secret.yaml). +* `clusterid`: `630372ccdc720a92c681fb928f27b53f` is the ID of the cluster + which will be used by Heketi when provisioning the volume. It can also be a + list of clusterids, for example: + `"8452344e2becec931ece4e33c4674e4e,42982310de6c63381718ccfa6d8cf397"`. This + is an optional parameter. +* `gidMin`, `gidMax` : The minimum and maximum value of GID range for the + storage class. A unique value (GID) in this range ( gidMin-gidMax ) will be + used for dynamically provisioned volumes. These are optional values. If not + specified, the volume will be provisioned with a value between 2000-2147483647 + which are defaults for gidMin and gidMax respectively. +* `volumetype` : The volume type and its parameters can be configured with this + optional value. If the volume type is not mentioned, it's up to the provisioner + to decide the volume type. + For example: + 'Replica volume': + `volumetype: replicate:3` where '3' is replica count. + 'Disperse/EC volume': + `volumetype: disperse:4:2` where '4' is data and '2' is the redundancy count. + 'Distribute volume': + `volumetype: none` + + For available volume types and administration options, refer to the +[Administration Guide](https://access.redhat.com/documentation/en-US/Red_Hat_Storage/3.1/html/Administration_Guide/part-Overview.html). + + For further reference information, see +[How to configure Heketi](https://github.com/heketi/heketi/wiki/Setting-up-the-topology). + + When persistent volumes are dynamically provisioned, the Gluster plugin +automatically creates an endpoint and a headless service in the name +`gluster-dynamic-`. The dynamic endpoint and service are automatically +deleted when the persistent volume claim is deleted. + +### OpenStack Cinder + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: gold +provisioner: kubernetes.io/cinder +parameters: + type: fast + availability: nova +``` + +* `type`: [VolumeType](https://docs.openstack.org/user-guide/dashboard-manage-volumes.html) + created in Cinder. Default is empty. +* `availability`: Availability Zone. If not specified, volumes are generally + round-robin-ed across all active zones where Kubernetes cluster has a node. + +### vSphere + +1. Create a StorageClass with a user specified disk format. + + kind: StorageClass + apiVersion: storage.k8s.io/v1 + metadata: + name: fast + provisioner: kubernetes.io/vsphere-volume + parameters: + diskformat: zeroedthick + + `diskformat`: `thin`, `zeroedthick` and `eagerzeroedthick`. Default: `"thin"`. + +2. Create a StorageClass with a disk format on a user specified datastore. + + kind: StorageClass + apiVersion: storage.k8s.io/v1 + metadata: + name: fast + provisioner: kubernetes.io/vsphere-volume + parameters: + diskformat: zeroedthick + datastore: VSANDatastore + + `datastore`: The user can also specify the datastore in the StorageClass. + The volume will be created on the datastore specified in the storage class, + which in this case is `VSANDatastore`. This field is optional. If the + datastore is not specified, then the volume will be created on the datastore + specified in the vSphere config file used to initialize the vSphere Cloud + Provider. + +3. Storage Policy Management inside kubernetes + + * Using existing vCenter SPBM policy + + One of the most important features of vSphere for Storage Management is + policy based Management. Storage Policy Based Management (SPBM) is a + storage policy framework that provides a single unified control plane + across a broad range of data services and storage solutions. SPBM enables + vSphere administrators to overcome upfront storage provisioning challenges, + such as capacity planning, differentiated service levels and managing + capacity headroom. + + The SPBM policies can be specified in the StorageClass using the + `storagePolicyName` parameter. + + * Virtual SAN policy support inside Kubernetes + + Vsphere Infrastructure (VI) Admins will have the ability to specify custom + Virtual SAN Storage Capabilities during dynamic volume provisioning. You + can now define storage requirements, such as performance and availability, + in the form of storage capabilities during dynamic volume provisioning. + The storage capability requirements are converted into a Virtual SAN + policy which are then pushed down to the Virtual SAN layer when a + persistent volume (virtual disk) is being created. The virtual disk is + distributed across the Virtual SAN datastore to meet the requirements. + + You can see [Storage Policy Based Management for dynamic provisioning of volumes](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/policy-based-mgmt.html) + for more details on how to use storage policies for persistent volumes + management. + +There are few +[vSphere examples](https://github.com/kubernetes/examples/tree/master/staging/volumes/vsphere) +which you try out for persistent volume management inside Kubernetes for vSphere. + +### Ceph RBD + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: fast +provisioner: kubernetes.io/rbd +parameters: + monitors: 10.16.153.105:6789 + adminId: kube + adminSecretName: ceph-secret + adminSecretNamespace: kube-system + pool: kube + userId: kube + userSecretName: ceph-secret-user + fsType: ext4 + imageFormat: "2" + imageFeatures: "layering" +``` + +* `monitors`: Ceph monitors, comma delimited. This parameter is required. +* `adminId`: Ceph client ID that is capable of creating images in the pool. + Default is "admin". +* `adminSecretNamespace`: The namespace for `adminSecret`. Default is "default". +* `adminSecret`: Secret Name for `adminId`. This parameter is required. + The provided secret must have type "kubernetes.io/rbd". +* `pool`: Ceph RBD pool. Default is "rbd". +* `userId`: Ceph client ID that is used to map the RBD image. Default is the + same as `adminId`. +* `userSecretName`: The name of Ceph Secret for `userId` to map RBD image. It + must exist in the same namespace as PVCs. This parameter is required. + The provided secret must have type "kubernetes.io/rbd", e.g. created in this + way: + ``` + $ kubectl create secret generic ceph-secret --type="kubernetes.io/rbd" \ + --from-literal=key='QVFEQ1pMdFhPUnQrSmhBQUFYaERWNHJsZ3BsMmNjcDR6RFZST0E9PQ==' \ + --namespace=kube-system + ``` +* `fsType`: fsType that is supported by kubernetes. Default: `"ext4"`. +* `imageFormat`: Ceph RBD image format, "1" or "2". Default is "1". +* `imageFeatures`: This parameter is optional and should only be used if you + set `imageFormat` to "2". Currently supported features are `layering` only. + Default is "", and no features are turned on. + +#### Quobyte + +```yaml +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: slow +provisioner: kubernetes.io/quobyte +parameters: + quobyteAPIServer: "http://138.68.74.142:7860" + registry: "138.68.74.142:7861" + adminSecretName: "quobyte-admin-secret" + adminSecretNamespace: "kube-system" + user: "root" + group: "root" + quobyteConfig: "BASE" + quobyteTenant: "DEFAULT" +``` + +* `quobyteAPIServer`: API Server of Quobyte in the format + `"http(s)://api-server:7860"` +* `registry`: Quobyte registry to use to mount the volume. You can specify the + registry as ``:`` pair or if you want to specify multiple + registries you just have to put a comma between them e.q. + ``:,:,:``. + The host can be an IP address or if you have a working DNS you can also + provide the DNS names. +* `adminSecretNamespace`: The namespace for `adminSecretName`. + Default is "default". +* `adminSecretName`: secret that holds information about the Quobyte user and + the password to authenticate against the API server. The provided secret + must have type "kubernetes.io/quobyte", e.g. created in this way: + ``` + $ kubectl create secret generic quobyte-admin-secret \ + --type="kubernetes.io/quobyte" --from-literal=key='opensesame' \ + --namespace=kube-system + ``` +* `user`: maps all access to this user. Default is "root". +* `group`: maps all access to this group. Default is "nfsnobody". +* `quobyteConfig`: use the specified configuration to create the volume. You + can create a new configuration or modify an existing one with the Web + console or the quobyte CLI. Default is "BASE". +* `quobyteTenant`: use the specified tenant ID to create/delete the volume. + This Quobyte tenant has to be already present in Quobyte. + Default is "DEFAULT". + +### Azure Disk + +#### Azure Unmanaged Disk Storage Class + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: slow +provisioner: kubernetes.io/azure-disk +parameters: + skuName: Standard_LRS + location: eastus + storageAccount: azure_storage_account_name +``` + +* `skuName`: Azure storage account Sku tier. Default is empty. +* `location`: Azure storage account location. Default is empty. +* `storageAccount`: Azure storage account name. If a storage account is provided, + it must reside in the same resource group as the cluster, and `location` is + ignored. If a storage account is not provided, a new storage account will be + created in the same resource group as the cluster. + +#### New Azure Disk Storage Class (starting from v1.7.2) + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: slow +provisioner: kubernetes.io/azure-disk +parameters: + storageaccounttype: Standard_LRS + kind: Shared +``` + +* `storageaccounttype`: Azure storage account Sku tier. Default is empty. +* `kind`: Possible values are `shared` (default), `dedicated`, and `managed`. + When `kind` is `shared`, all unmanaged disks are created in a few shared + storage accounts in the same resource group as the cluster. When `kind` is + `dedicated`, a new dedicated storage account will be created for the new + unmanaged disk in the same resource group as the cluster. + +- Premium VM can attach both Standard_LRS and Premium_LRS disks, while Standard + VM can only attach Standard_LRS disks. +- Managed VM can only attach managed disks and unmanaged VM can only attach + unmanaged disks. + +### Azure File + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: azurefile +provisioner: kubernetes.io/azure-file +parameters: + skuName: Standard_LRS + location: eastus + storageAccount: azure_storage_account_name +``` + +* `skuName`: Azure storage account Sku tier. Default is empty. +* `location`: Azure storage account location. Default is empty. +* `storageAccount`: Azure storage account name. Default is empty. If a storage + account is not provided, all storage accounts associated with the resource + group are searched to find one that matches `skuName` and `location`. If a + storage account is provided, it must reside in the same resource group as the + cluster, and `skuName` and `location` are ignored. + +During provision, a secret is created for mounting credentials. If the cluster +has enabled both [RBAC](/docs/admin/authorization/rbac/) and +[Controller Roles](/docs/admin/authorization/rbac/#controller-roles), add the +`create` permission of resource `secret` for clusterrole +`system:controller:persistent-volume-binder`. + +### Portworx Volume + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: portworx-io-priority-high +provisioner: kubernetes.io/portworx-volume +parameters: + repl: "1" + snap_interval: "70" + io_priority: "high" + +``` + +* `fs`: filesystem to be laid out: [none/xfs/ext4] (default: `ext4`). +* `block_size`: block size in Kbytes (default: `32`). +* `repl`: number of synchronous replicas to be provided in the form of + replication factor [1..3] (default: `1`) A string is expected here i.e. + `"1"` and not `1`. +* `io_priority`: determines whether the volume will be created from higher + performance or a lower priority storage [high/medium/low] (default: `low`). +* `snap_interval`: clock/time interval in minutes for when to trigger snapshots. + Snapshots are incremental based on difference with the prior snapshot, 0 + disables snaps (default: `0`). A string is expected here i.e. + `"70"` and not `70`. +* `aggregation_level`: specifies the number of chunks the volume would be + distributed into, 0 indicates a non-aggregated volume (default: `0`). A string + is expected here i.e. `"0"` and not `0` +* `ephemeral`: specifies whether the volume should be cleaned-up after unmount + or should be persistent. `emptyDir` use case can set this value to true and + `persistent volumes` use case such as for databases like Cassandra should set + to false, [true/false] (default `false`). A string is expected here i.e. + `"true"` and not `true`. + +### ScaleIO + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: slow +provisioner: kubernetes.io/scaleio +parameters: + gateway: https://192.168.99.200:443/api + system: scaleio + protectionDomain: pd0 + storagePool: sp1 + storageMode: ThinProvisioned + secretRef: sio-secret + readOnly: false + fsType: xfs +``` + +* `provisioner`: attribute is set to `kubernetes.io/scaleio` +* `gateway`: address to a ScaleIO API gateway (required) +* `system`: the name of the ScaleIO system (required) +* `protectionDomain`: the name of the ScaleIO protection domain (required) +* `storagePool`: the name of the volume storage pool (required) +* `storageMode`: the storage provision mode: `ThinProvisioned` (default) or + `ThickProvisioned` +* `secretRef`: reference to a configured Secret object (required) +* `readOnly`: specifies the access mode to the mounted volume (default false) +* `fsType`: the file system to use for the volume (default ext4) + +The ScaleIO Kubernetes volume plugin requires a configured Secret object. +The secret must be created with type `kubernetes.io/scaleio` and use the same +namespace value as that of the PVC where it is referenced +as shown in the following command: + +```shell +kubectl create secret generic sio-secret --type="kubernetes.io/scaleio" \ +--from-literal=username=sioadmin --from-literal=password=d2NABDNjMA== \ +--namespace=default +``` + +### StorageOS + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: fast +provisioner: kubernetes.io/storageos +parameters: + pool: default + description: Kubernetes volume + fsType: ext4 + adminSecretNamespace: default + adminSecretName: storageos-secret +``` + +* `pool`: The name of the StorageOS distributed capacity pool to provision the + volume from. Uses the `default` pool which is normally present if not specified. +* `description`: The description to assign to volumes that were created dynamically. + All volume descriptions will be the same for the storage class, but different + storage classes can be used to allow descriptions for different use cases. + Defaults to `Kubernetes volume`. +* `fsType`: The default filesystem type to request. Note that user-defined rules + within StorageOS may override this value. Defaults to `ext4`. +* `adminSecretNamespace`: The namespace where the API configuration secret is + located. Required if adminSecretName set. +* `adminSecretName`: The name of the secret to use for obtaining the StorageOS + API credentials. If not specified, default values will be attempted. + +The StorageOS Kubernetes volume plugin can use a Secret object to specify an +endpoint and credentials to access the StorageOS API. This is only required when +the defaults have been changed. +The secret must be created with type `kubernetes.io/storageos` as shown in the +following command: + +```shell +kubectl create secret generic storageos-secret \ +--type="kubernetes.io/storageos" \ +--from-literal=apiAddress=tcp://localhost:5705 \ +--from-literal=apiUsername=storageos \ +--from-literal=apiPassword=storageos \ +--namespace=default +``` + +Secrets used for dynamically provisioned volumes may be created in any namespace +and referenced with the `adminSecretNamespace` parameter. Secrets used by +pre-provisioned volumes must be created in the same namespace as the PVC that +references it. From 578a831405b505fcecc0ac677c66db056b114c3b Mon Sep 17 00:00:00 2001 From: stewart-yu Date: Fri, 17 Nov 2017 12:41:47 +0800 Subject: [PATCH 32/53] fix deadlink url --- docs/reference/federation/v1/definitions.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/federation/v1/definitions.html b/docs/reference/federation/v1/definitions.html index 0870585fad..a7329fae7f 100755 --- a/docs/reference/federation/v1/definitions.html +++ b/docs/reference/federation/v1/definitions.html @@ -1103,7 +1103,7 @@ span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; }

phase

-

Phase is the current lifecycle phase of the namespace. More info: https://git.k8s.io/community/contributors/design-proposals/namespaces.md#phases

+

Phase is the current lifecycle phase of the namespace. More info: https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#phases

false

string

@@ -1192,7 +1192,7 @@ span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; }

finalizers

-

Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers

+

Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#finalizers

false

v1.FinalizerName array

From de2078ad27fa3c7bb0dd5a92410dba3c73fe2012 Mon Sep 17 00:00:00 2001 From: Shilla Date: Thu, 16 Nov 2017 23:47:01 -0500 Subject: [PATCH 33/53] updated prerequisites corrected Prerequsites typo --- docs/getting-started-guides/gce.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started-guides/gce.md b/docs/getting-started-guides/gce.md index d513e33406..ae3864d2c7 100644 --- a/docs/getting-started-guides/gce.md +++ b/docs/getting-started-guides/gce.md @@ -169,7 +169,7 @@ can be done in the Google Cloud Console. See the [Google Cloud Storage JSON API Overview](https://cloud.google.com/storage/docs/json_api/) for more details. -Also ensure that-- as listed in the [Prerequsites section](#prerequisites)-- you've enabled the `Compute Engine Instance Group Manager API`, and can start up a GCE VM from the command line as in the [GCE Quickstart](https://cloud.google.com/compute/docs/quickstart) instructions. +Also ensure that-- as listed in the [Prerequisites section](#prerequisites)-- you've enabled the `Compute Engine Instance Group Manager API`, and can start up a GCE VM from the command line as in the [GCE Quickstart](https://cloud.google.com/compute/docs/quickstart) instructions. #### Cluster initialization hang From 9f10c5a9708d96efbf836b3ccceb85ac86f9a8f9 Mon Sep 17 00:00:00 2001 From: Shilla Date: Fri, 17 Nov 2017 00:11:30 -0500 Subject: [PATCH 34/53] general clean up fixed a typo that didn't make sense changed do to to --- .../getting-started-guides/ubuntu/operational-considerations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started-guides/ubuntu/operational-considerations.md b/docs/getting-started-guides/ubuntu/operational-considerations.md index 9e0a24a666..9c4a916a3a 100644 --- a/docs/getting-started-guides/ubuntu/operational-considerations.md +++ b/docs/getting-started-guides/ubuntu/operational-considerations.md @@ -153,7 +153,7 @@ certificate (with ```myregistry.company.com``` as Common Name) in the juju run-action kubernetes-worker/0 registry domain=myregistry.company.com htpasswd="$(base64 -w0 htpasswd)" htpasswd-plain="$(base64 -w0 htpasswd-plain)" tlscert="$(base64 -w0 registry.crt)" tlskey="$(base64 -w0 registry.key)" ingress=true ``` -If you then decide that you want do delete the registry, just run: +If you then decide that you want to delete the registry, just run: ``` juju run-action kubernetes-worker/0 registry delete=true ingress=true From 49cba3dc341c88ce1d624998d6433f55f63bf671 Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Tue, 14 Nov 2017 21:19:27 +0800 Subject: [PATCH 35/53] Update proxies.md Update the list num --- docs/concepts/cluster-administration/proxies.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/concepts/cluster-administration/proxies.md b/docs/concepts/cluster-administration/proxies.md index 6767bea3bf..33ccf35fd5 100644 --- a/docs/concepts/cluster-administration/proxies.md +++ b/docs/concepts/cluster-administration/proxies.md @@ -12,7 +12,7 @@ This page explains proxies used with Kubernetes. There are several different proxies you may encounter when using Kubernetes: - 1. The [kubectl proxy](/docs/tasks/access-application-cluster/access-cluster/#directly-accessing-the-rest-api): +1. The [kubectl proxy](/docs/tasks/access-application-cluster/access-cluster/#directly-accessing-the-rest-api): - runs on a user's desktop or in a pod - proxies from a localhost address to the Kubernetes apiserver @@ -21,7 +21,7 @@ There are several different proxies you may encounter when using Kubernetes: - locates apiserver - adds authentication headers - 1. The [apiserver proxy](/docs/tasks/access-application-cluster/access-cluster/#discovering-builtin-services): +1. The [apiserver proxy](/docs/tasks/access-application-cluster/access-cluster/#discovering-builtin-services): - is a bastion built into the apiserver - connects a user outside of the cluster to cluster IPs which otherwise might not be reachable @@ -31,7 +31,7 @@ There are several different proxies you may encounter when using Kubernetes: - can be used to reach a Node, Pod, or Service - does load balancing when used to reach a Service - 1. The [kube proxy](/docs/concepts/services-networking/service/#ips-and-vips): +1. The [kube proxy](/docs/concepts/services-networking/service/#ips-and-vips): - runs on each node - proxies UDP and TCP @@ -39,13 +39,13 @@ There are several different proxies you may encounter when using Kubernetes: - provides load balancing - is just used to reach services - 1. A Proxy/Load-balancer in front of apiserver(s): +1. A Proxy/Load-balancer in front of apiserver(s): - existence and implementation varies from cluster to cluster (e.g. nginx) - sits between all clients and one or more apiservers - acts as load balancer if there are several apiservers. - 1. Cloud Load Balancers on external services: +1. Cloud Load Balancers on external services: - are provided by some cloud providers (e.g. AWS ELB, Google Cloud Load Balancer) - are created automatically when the Kubernetes service has type `LoadBalancer` From ad68acc4311bba984d9da102032de099837f0a11 Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Sun, 19 Nov 2017 12:08:49 +0800 Subject: [PATCH 36/53] Update index.md Fix deadlink. --- docs/admin/federation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/federation/index.md b/docs/admin/federation/index.md index 7701448164..9127a1aa36 100644 --- a/docs/admin/federation/index.md +++ b/docs/admin/federation/index.md @@ -385,4 +385,4 @@ if required. ## For more information - * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation/federation.md) details use cases that motivated this work. + * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/multicluster/federation.md) details use cases that motivated this work. From a4616127797604ae536f065b0b81bb5e8c9d05c4 Mon Sep 17 00:00:00 2001 From: chenpengdev Date: Sun, 19 Nov 2017 15:08:26 +0800 Subject: [PATCH 37/53] fix broken link --- docs/concepts/storage/persistent-volumes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md index 608a5bcda9..4dccc7bc75 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/docs/concepts/storage/persistent-volumes.md @@ -113,7 +113,7 @@ However, the particular path specified in the custom recycler pod template in th #### Deleting -For volume plugins that support the Delete reclaim policy, deletion removes both the `PersistentVolume` object from Kubernetes, as well as deleting the associated storage asset in the external infrastructure, such as an AWS EBS, GCE PD, Azure Disk, or Cinder volume. Volumes that were dynamically provisioned inherit the [reclaim policy of their `StorageClass`](#reclaim-policy-1), which defaults to Delete. The administrator should configure the `StorageClass` according to users' expectations, otherwise the PV must be edited or patched after it is created. See [Change the Reclaim Policy of a PersistentVolume](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/). +For volume plugins that support the Delete reclaim policy, deletion removes both the `PersistentVolume` object from Kubernetes, as well as deleting the associated storage asset in the external infrastructure, such as an AWS EBS, GCE PD, Azure Disk, or Cinder volume. Volumes that were dynamically provisioned inherit the [reclaim policy of their `StorageClass`](#reclaim-policy), which defaults to Delete. The administrator should configure the `StorageClass` according to users' expectations, otherwise the PV must be edited or patched after it is created. See [Change the Reclaim Policy of a PersistentVolume](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/). ### Expanding Persistent Volumes Claims From 83ebbbfa9749759c78ea91ad2eabf260a8456ece Mon Sep 17 00:00:00 2001 From: chenpengdev Date: Sun, 19 Nov 2017 15:30:45 +0800 Subject: [PATCH 38/53] delete the command prompt --- docs/concepts/storage/storage-classes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/concepts/storage/storage-classes.md b/docs/concepts/storage/storage-classes.md index 1aa8ed31e8..0acfb65309 100644 --- a/docs/concepts/storage/storage-classes.md +++ b/docs/concepts/storage/storage-classes.md @@ -221,7 +221,7 @@ parameters: `secretNamespace` and `secretName` are omitted. The provided secret must have type "kubernetes.io/glusterfs", e.g. created in this way: ``` - $ kubectl create secret generic heketi-secret \ + kubectl create secret generic heketi-secret \ --type="kubernetes.io/glusterfs" --from-literal=key='opensesame' \ --namespace=default ``` @@ -378,7 +378,7 @@ parameters: The provided secret must have type "kubernetes.io/rbd", e.g. created in this way: ``` - $ kubectl create secret generic ceph-secret --type="kubernetes.io/rbd" \ + kubectl create secret generic ceph-secret --type="kubernetes.io/rbd" \ --from-literal=key='QVFEQ1pMdFhPUnQrSmhBQUFYaERWNHJsZ3BsMmNjcDR6RFZST0E9PQ==' \ --namespace=kube-system ``` @@ -421,7 +421,7 @@ parameters: the password to authenticate against the API server. The provided secret must have type "kubernetes.io/quobyte", e.g. created in this way: ``` - $ kubectl create secret generic quobyte-admin-secret \ + kubectl create secret generic quobyte-admin-secret \ --type="kubernetes.io/quobyte" --from-literal=key='opensesame' \ --namespace=kube-system ``` From 6c95dfe603b4ba1dfd88563149743de69b3f377d Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Sun, 12 Nov 2017 20:32:43 +0800 Subject: [PATCH 39/53] Update create-cluster-kubeadm.md Fix some text error. --- docs/setup/independent/create-cluster-kubeadm.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/setup/independent/create-cluster-kubeadm.md b/docs/setup/independent/create-cluster-kubeadm.md index dc03495517..97a11215f9 100644 --- a/docs/setup/independent/create-cluster-kubeadm.md +++ b/docs/setup/independent/create-cluster-kubeadm.md @@ -225,7 +225,6 @@ kubectl apply -f **NOTE:** You can install **only one** pod network per cluster. - {% capture choose %} Please select one of the tabs to see installation instructions for the respective third-party Pod Network Provider. {% endcapture %} @@ -263,13 +262,16 @@ kubectl apply -f https://raw.githubusercontent.com/projectcalico/canal/master/k8 **Note:** - - For flannel to work correctly, `--pod-network-cidr=10.244.0.0/16` has to be passed to `kubeadm init`. - - flannel works on `amd64`, `arm`, `arm64` and `ppc64le`, but for it to work on an other platform than + - For `flannel` to work correctly, `--pod-network-cidr=10.244.0.0/16` has to be passed to `kubeadm init`. + - `flannel` works on `amd64`, `arm`, `arm64` and `ppc64le`, but for it to work on a platform other than `amd64` you have to manually download the manifest and replace `amd64` occurences with your chosen platform. ```shell kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/v0.9.0/Documentation/kube-flannel.yml ``` + + - For more information about `flannel`, please see [here](https://github.com/coreos/flannel). + {% endcapture %} {% capture kube-router %} @@ -278,7 +280,7 @@ Kube-router relies on kube-controll-manager to allocate pod CIDR for the nodes. Kube-router provides pod networking, network policy, and high-performing IP Virtual Server(IPVS)/Linux Virtual Server(LVS) based service proxy. -For information on setting up Kubernetes cluster with Kube-router using kubeadm please see official [setup guide](https://github.com/cloudnativelabs/kube-router/blob/master/Documentation/kubeadm.md). +For information on setting up Kubernetes cluster with Kube-router using kubeadm, please see official [setup guide](https://github.com/cloudnativelabs/kube-router/blob/master/Documentation/kubeadm.md). {% endcapture %} From a5dd0ebd15e3128a82d2d2558f3184d0e2c00bea Mon Sep 17 00:00:00 2001 From: Stewart-YU Date: Mon, 20 Nov 2017 10:23:07 +0800 Subject: [PATCH 40/53] Update multiple-zones.md Fix bad link. --- docs/admin/multiple-zones.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/multiple-zones.md b/docs/admin/multiple-zones.md index e58bfd59fc..3f590016c0 100644 --- a/docs/admin/multiple-zones.md +++ b/docs/admin/multiple-zones.md @@ -11,7 +11,7 @@ title: Running in Multiple Zones Kubernetes 1.2 adds support for running a single cluster in multiple failure zones (GCE calls them simply "zones", AWS calls them "availability zones", here we'll refer to them as "zones"). This is a lightweight version of a broader Cluster Federation feature (previously referred to by the affectionate -nickname ["Ubernetes"](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/federation/federation.md)). +nickname ["Ubernetes"](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/multicluster/federation.md)). Full Cluster Federation allows combining separate Kubernetes clusters running in different regions or cloud providers (or on-premises data centers). However, many From c385203bebdc624fea60d2faa4933415656d7cf3 Mon Sep 17 00:00:00 2001 From: Wang Jie Date: Mon, 20 Nov 2017 10:56:31 +0800 Subject: [PATCH 41/53] Update scheduling-gpus.md --- docs/tasks/manage-gpus/scheduling-gpus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tasks/manage-gpus/scheduling-gpus.md b/docs/tasks/manage-gpus/scheduling-gpus.md index 1d4b743fd3..7e396d51fc 100644 --- a/docs/tasks/manage-gpus/scheduling-gpus.md +++ b/docs/tasks/manage-gpus/scheduling-gpus.md @@ -149,7 +149,7 @@ spec: - Support for hardware accelerators is in its early stages in Kubernetes. - GPUs and other accelerators will soon be a native compute resource across the system. - Better APIs will be introduced to provision and consume accelerators in a scalable manner. -- Kubernetes will automatically ensure that applications consuming GPUs gets the best possible performance. +- Kubernetes will automatically ensure that applications consuming GPUs get the best possible performance. - Key usability problems like access to CUDA libraries will be addressed. {% endcapture %} From cc09a91e0549c67da857e619a52d8fdf31ad1a0a Mon Sep 17 00:00:00 2001 From: craigbox Date: Mon, 20 Nov 2017 12:16:18 +0000 Subject: [PATCH 42/53] There's no appendix; remove # APPENDIX heading (also, why was it shouted?) --- docs/admin/authentication.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/admin/authentication.md b/docs/admin/authentication.md index 788ddc3828..95604f4e79 100644 --- a/docs/admin/authentication.md +++ b/docs/admin/authentication.md @@ -684,7 +684,3 @@ rules: verbs: ["impersonate"] resourceNames: ["view", "development"] ``` - -## APPENDIX - - From f0ce92e69d54b97aed9a04a99dfce21597cf3ec5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81d=C3=A1m=20S=C3=A1ndor?= Date: Mon, 20 Nov 2017 15:16:21 +0100 Subject: [PATCH 43/53] Mention readiness probe in configuration section The configuration values section only mentions liveness probes which is confusing for the reader. Additionally liveness and readiness probes behave differently if they time out. Readiness probe will not restart the Pod but the documentation looks like it would. --- .../configure-liveness-readiness-probes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md b/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md index ffd94bebfd..86ad07ecd9 100644 --- a/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md +++ b/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md @@ -252,7 +252,7 @@ you can use to more precisely control the behavior of liveness and readiness checks: * `initialDelaySeconds`: Number of seconds after the container has started -before liveness probes are initiated. +before liveness or readiness probes are initiated. * `periodSeconds`: How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. * `timeoutSeconds`: Number of seconds after which the probe times out. Defaults @@ -261,7 +261,7 @@ to 1 second. Minimum value is 1. considered successful after having failed. Defaults to 1. Must be 1 for liveness. Minimum value is 1. * `failureThreshold`: When a Pod starts and the probe fails, Kubernetes will -try `failureThreshold` times before giving up and restarting the Pod. +try `failureThreshold` times before giving up. Giving up in case of liveness probe means restarting the Pod. In case of readiness probe the Pod will be marked Unready. Defaults to 3. Minimum value is 1. [HTTP probes](/docs/api-reference/{{page.version}}/#httpgetaction-v1-core) From 0a7b3020d8bff1a893f09b7c4a264691a051eb3e Mon Sep 17 00:00:00 2001 From: Martin Polednik Date: Mon, 20 Nov 2017 15:22:54 +0100 Subject: [PATCH 44/53] typo fix in device_plugins concepts Signed-off-by: Martin Polednik --- docs/concepts/cluster-administration/device-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/cluster-administration/device-plugins.md b/docs/concepts/cluster-administration/device-plugins.md index eb689f535b..635c8232b2 100644 --- a/docs/concepts/cluster-administration/device-plugins.md +++ b/docs/concepts/cluster-administration/device-plugins.md @@ -49,7 +49,7 @@ Then, developers can request devices in a [Container](/docs/api-reference/{{page.version}}/#container-v1-core) specification by using the same process that is used for [opaque integer resources](/docs/tasks/configure-pod-container/opaque-integer-resource/). -In version 1.8, extended resources are spported only as integer resources and must have +In version 1.8, extended resources are supported only as integer resources and must have `limit` equal to `request` in the Container specification. ## Device plugin implementation From 2e927c806e9838268cb4e90e2aefbab37b192511 Mon Sep 17 00:00:00 2001 From: Michael Ducy Date: Mon, 20 Nov 2017 12:57:28 -0500 Subject: [PATCH 45/53] Update Sysdig partner logo and blurb. --- _includes/partner-script.js | 4 ++-- images/square-logos/sys_dig.png | Bin 7002 -> 4675 bytes 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_includes/partner-script.js b/_includes/partner-script.js index 6364e5da73..39357ab2fa 100644 --- a/_includes/partner-script.js +++ b/_includes/partner-script.js @@ -2,10 +2,10 @@ var partners = [ { type: 0, - name: 'Sysdig Cloud', + name: 'Sysdig', logo: 'sys_dig', link: 'https://sysdig.com/blog/monitoring-kubernetes-with-sysdig-cloud/', - blurb: 'Container native monitoring with deep support for Kubernetes.' + blurb: 'Sysdig is the container intelligence company. Sysdig has created the only unified platform to deliver monitoring, security, and troubleshooting in a microservices-friendly architecture.' }, { type: 0, diff --git a/images/square-logos/sys_dig.png b/images/square-logos/sys_dig.png index c49f58a670d49af7e30d5615092817ee515da197..eea97119fc0b7e04f3ba428d5a01c5433fef9927 100644 GIT binary patch literal 4675 zcmb_ghd0}A7ym}=k(w21w?(T6YS$`?meLxfYE!FHirNINJzBMb64c(B)*dkut7h%m zl!(#(V#I#+e|XPx?&scf&w0*y&U4RQpJ;=}S`4(Dv;Y7w=xA#^z0?Jll1fc^iEZ85 z)0c|U_K}tbaPjY;T8chhdT89W%{(t}O#Tzlec?>sODC0=j-Dpf5*;fejQ!|mI41xw z4eMyA8Trm^&jkb;ts$xYED*Di06%*aZI8<>T1yj`6zVxvdMVEc)i5=c@sc$E3TfZY zifxxN_~b^>+$OxNsgVp+=HP7(o1lY+@q4}m%znny8NU$c%j0{<-23^4=e*;Ew!o)V z-ItO`a`x<9tH8mmlauCMzxl&vA>ckW|2xM2GsxKv8*HbuvnM#k6(fg9Jn2OU7|r5G zzyY=dK)p4ldfVS7K*i(zytZ*qxdhhKdJA}-t+dA3RtHh25OiCeYagmVo)5=bI7B8|ZfV|7lednKjrorQO};4gG!UK< zS|C%mkn**;(K6;?m}IV&cjr3Zhs9k8kbbvLl5h?3IEdK~Nm))p#W}y$@$jddE(2xB z>aI^eSS*w5zy0jdM}}TEug?D_V4IZS6o-S@_W62~0t0 zu7ziDx-+nn6O~k68>6Ca%8)gwIC*2jC)}M9kyY8vZ6ch0wIzFK{X`k+0O)~-X$vLe zd$^a}NsI2E2?(C17fA%3&+yYV7`gpq!y7Yooh1rpTOG8ry*|a#uVRFklN#M)@TYOM z4*-m|OGUbebmpF2=BoOclQV=D;TQRLo>ODbDn6Fh(LU7}uD@K9l8X`x%ku-?V4zp{ z=v3(tlw@z67e!U8kW!9=$D^Z9gOVxWAOsVnlRphy-$2Y+K&95U+GEIoI-Z?tI8}vk zlfTOyOyKFkb)rRn4~bPHG2DX&YS=`^42*(wtrvHxO*IVIGG*ZBQ+w$uDy3mb@={p+ z9aTP51mPaD!ti|3vX?+GRGmcWglHX`ig*Xc?qwW?;Uxe&O82(33=(G?kF0(pr_r57v^u#nOE(=C1pK;+c?iVw0-sg}@SO(md;k zun0nXN8QieETW~Qy{(|2P{{N|uc!7cz`$D z$-TsDmE!*3IQg@xD8gYX>w=WW(ahDN94p$kNOCyXqs`W{*TBo-#|vrz@|JG94VAeu1{T ztkYr=8 zFK#d+$7Bg8pKy$I;z#hlLg9St5A2 z3w4$8fNTo9amdi=>)08=5bz1o2UfY2ty?|BV*mq*UPka!n{Rrm0=uce-TG|i=ZV3L zBEr)AIA>m&4b|o|_*~<+eZu0)L5i_aWoZEs9N0R4?BHWmD^&N2e3m;uV%vhkkL=@L zIag8uC4D%ehF+JF#6>3Nz|e$3@impP5xBLbTwOO!5biJ6159*5R^vQYqcsTB~VylD=K1$aM43+tgly^pP%dofu&kH z6cjn8R0JSWg?K+$V3Y(f`}er)j8r8yxzbp6dVc)y7E%t@8X|Mw2-?h>`u4u%@pV^u z+?wf}Xo-NG6zH5hf2{=yLS8B4Lr6uQNVsPF{uO1@rq(V1T&Mc*Q%|S$u;Ne4J43CG zASAACpznF(`5CJPkwiXu?O8}?SnnX{(d%xxx%bmZJDH3^dD)LPmDVs4g(8}j{7%$3 zX7knO~mrZHcD&ee2Rbp+`DvPen@0%6twzlO4G% ztFo8=`WC+HTuRJihtHt#T!=SZ&vzV~h;1_&jj`O2|89aDIMH;7SkoNp`#h@aWP2_- z%QYpeT{SynaNwkIXN5+4Nmncpw_+P#G<-CgTQ@{)+NqHvNi?<1V(9o~^ww*6d{sOd zdm6{acI$Io|G$o~PGcOk(~-T3ZfM#{%T!N>U?OrxpFf!mj2t3V@%=8qxc}*% z@8r`s=762G`t(1vX9f8dKbx1E%sq1xVy~b=G&VNceU4~?qNiw$RmKAv7Iuf;QpeFV zTH)Q5^!Qo_YRkVpnGJa~drFQtHA+qdt!U9_Z5oW^z}?&$Bo%lMj{@IYa~c?6OO%r5 zh7y~go4<0?x#z1LSEqpoLg!8^alzO*OZ(wO5E|Dqx%ghUc+c-g+S$=L5BI(PT4fNa z?IaZ}?xlU7j%#P_xN<%yAQ7g9n(MS{l_Iz|cpMMJKXdWrIFXtYr`P29c6Za1+sLUiuH zO*%Tduhi+=?mHr%6>QZRlLuR#0hF`HSN_$~h~*L##*<%}Hf9q96Ja^6uNj~} zw1A$6jE-ZxF;C(;Ax$<`VWxAOjHu zI!A`R0N!QNO2S;n5<`_4f7zFcvqcTY1y$7$ycXo+-~EB&zP>(6M2=_i)ll^dqi#r> z3NIuw(?0=<4;VShkV^g3emeU-d|Od3v7vZK81%Jsm3dzAXA8Xc)6UXxnW8V=2lri{32qAqv+uZjBAEP!H zwqPSvc5IUH$5CuHodG)`SL9F6l6utK8nWv>^4LLkwMz5bsAxD>$F&y*lER_U=;U=c zj>ts~4Oc>9HQ$FkQng-`FIFnnigYk@{r26F?6eJ{k~7NoYR)co971TA+xgBr{`2Pm zRsG?;(4hVOeZuDi^KT`ab|PF^6w3l+$9trJx%F<#Dj%CRQI@4H8)#m6{9m*}kZIUc ziT5n8%I-1PWxjr>CgS&+dBs^#D$O`Ze#$Pgb4id=Y0b;y}%yRQzU1gD5n0) zuI;_6gfrj6+o=x5lB(B**mc}vnUw_6-0-643reExVgEB zfc7}&bDe?19h7q?>Ya)g9cB1zc<$miK4m0gk}GVdT%DV)vjl^x#0RQJgJu@1PhX>d zT+>VRoB!3|DRdmz`svcT&WFpa?@6T|QxkroXBY*y8cjs8Vr5_)4< ziU9{(H4@MBm2|gYr(PRplAgG$>soRP%Tp2$9V~l&g|Yez4js=G^9~XC>w@JJ_135p zpYE!wE;Q|l*hf@q{!ePz<)7mhyo02q3<7Fh#_YZ)p9fyxIq$Vd`ASIHPW|!wp#boL zyb$db09IyI6Bh5}jRa_BXO zaSVL}dwVL<-|sF^ElxqpxU9S1Pd^f|qC_+@hkTFyb@V-Up68^eQGXc%61{zglDMw} zaZ=Ve3slTYX&uPL^nhS2i`ipkw)FiHTPJqtmpP>7b0JWxpvimrVc$hRT;KAc{)CLr zT8TZgwWK#yEm=BurujEvV)n+_h-z33JHO!k?P_NtNI%UtThpYn8zR|hor=e zjPO!#osc3(UO%PB>sPkP@9yVLRjq4Z2>yoA6FX}ZTK#;WU zM%MNw=u7iDxZAh;6PjK1c{wX}Am3RVKO8EI8OWISRzYw-+3veeyLl&J!w`GN>O=v! zJ72%(6;mAlIV7^y6GhqX7Jv7gqiD#ct?@Wa!oU=KKPUvy#s8RMdm#3L1~@f4fJ@2Q^=~Ezbif79W0YE4w{(=hE)+njd3uX zAXO(usKUTKL(+*kid}N!IipptL9oNHZ^YYUrz)|*eZfL}BSmmUJ#Czoy{Oe;l~Qn% z%{lUU83SOu?gs{w#rw&3{h^} z1&|wAv{+zMbxJQzw%u0-3Ng7MNxOV_qCd(MLNDK(5jDCv^oICzDz zv*o0l{j~>s%{&Wp8h2|P9h1sL`yaZvkJvSlf6ptc4s2K)PO2iUkS ztZ9aT7{%*~dvsUmMh*(#UG+t3Xjt#eQ96_9HoGRDKr}GRbXUzI;|)H zug5i~(zKX&QLF0{4r@Zlh40)MC@n94wN+K?doPM+0GB&xc{7HD|5T zu+o|WKPtoui)l+3@>=vpl0DH?I3w*F+Lq|f9ya874q1E#Y(05i;5w=ai0;gqt+JW) z+{Q2s5~S0Z4Cvh{)ZZiV;IvqRQPXDi+yPCshad}_$~{S)$~)V^%vk5J^@O44a@(kB zaAu22(0Bhtp`kMw{#Lkg)t%h_a_C&8o>kec?97le34(8DIC*p#s*3pp`}uK)R$aGs zx;7lauyLNDIP=mBQ>y0U#RaatF*%n$*6h!ixDSK&xtEOwq#nN6EE2cV?O`w$`^}qD6&kqKK!kp;a;eswEac7)Ux$V2c6PXXhL;iZ+ kg8ct!kAE~u*YL3l0)umiOw-T5qDb7@$zz;DHlV@)tu@YtNm|J zxYe|%;XWVKe*SFG5>mha6Lo4eX^`4Hj$$k`_|PMuro_$T6{C9PidTmU-`(^++b#SV z=|;BrXE#6RQ5@m0m$;IFi|QM=H+&CIk{dp3f-tJ-{-2-wJ1-}tV?~%wf1I-_Bl0!6 zzj*U|*@r`(v9YRYqA7TWUyyYjTrI8sSj~0gy;B&`e6CXY;|Ka)NFZWVn^Dz1rr7;t6k5KpoiXSeBDdPW7QK4pFz{JMRzCb*# zb{Z4#dH&qm+L~PQ4V|5x-FyIN1eYavTTxNL6=gY;dk-3ewPc|NhdYmde9>pCtfE4( z@m!Wk&vt&zR|rPcyD1<6+;@Y)!E6hw8uO|Iyn-zt`-n*5AwFO^g?LI z^+%b4WZaZdFc0{Jg5j86ht58?1R-%oe+{J!k<)!*OZ6SkjnCn1*V%e! z95xCz?KAp#2iyRa7viaG%EfoBV%E@$@_=+V8Fk< zRZ|Z72ZWEgl#sio7yj`xGL1-`tuXVJ|8&f&lnAf()wV-Q_qf_na;vqZt<|QvllwDQ7VP=YL23u z+}tXccKjPtQ&U^@1)_I$JS8(8HW_D9g|Ck9FKYM|7?fXIAFp`i*CaDcywYDQ!%bPl zZ*6HguQEe&;fhkk`8LkDN#|)JXx}9iu`C9d=T~^2AWa@pgd<_ERr2opwT(^IJ1VE4 z?6wAm_OC6Abc8l7KAKsGyQiIh0jfw#jzzp(rPkM?W`6|rx36tCqT<{veCc4}y&fXL zsZ)o9S^xe;ar#th+E(l_-sXCP-9rU4&;y7tv#^WYKg8*Z_`6*sv9@A8Ea(?p&_=Ii z8g`oKS3;(r<^JsWZ$S{XmR%7P_wL=>CY@RuKbL6??-M=_OIVcNmSaHStQw|tb#-5~ zx64ObvCu)pAFDine&91i!ox{nH&8WZ!pvHH>E!c^xat(dx{@X&79NAmo3S_^T6m|U zb}bt!m|&xVeKfnVG0S3jtu6^q28l1Bi0bUF4NUEymFjicuZbG5eSB5;LL~7+WY&hZG83n@ z5$68#5UL4NHt|KJ=uoLMaTmwKlxeZsSCxgm;aNBPcXQf;4h^)HUD~uu>t+y%k07?0 zc3lXqWG*OB_)W7X}9{+*!}wAg`RR^qRC5k zIQ;ap~f#=3Vjl*z(!nt3n#ur}A zD}qdyrrrE_6%@j-XQ!mFUlS9J1DnrFC0&2-F>t2f=}JfA5|~9ok9(LcPB@2&6RiQn z8$|rD&eklr3CsOiRSD|vaxoZ~+U2paG1tSnu=C%ot#WgJ|2~@;4n3$VI6OEIe#n=e zTe%LS>;n3V!SF~);kNzdj&@SQS~pJ*=PVq=vM2oI+IOOv&85G4=K2z5+Zav`8ahtZ z#o2s$uUrJ89fK__*1NrY$Kv=q!`j+fXtyWa%ggKSx(t+i(!F)(>u6qHUcvW)0r;N) z^LX`lP1>czi^|`0Mupr0!zsd7*Vjo~>s1|R;ZvLK0#M}v!Xfk2=0Q1w+;%4i!~`<` zE%k;)7@_S@^8Ws>rwJ@*R#2e8`-Fsq*7JjR`))P3&$a)yt`WZ&5$++~>WHgE>C_6A z%fge(%k%~Aa;C_ttE<;iDrpR<3zF3_zDie;GJf>57VS(Vx}F*FjDFGf4S4Dsdn^53 z;m7qOAI-kWAYdkcw^f&5y@=XqeCiWM|BsSp7W%JRJ(itP(0wOqWG`Gk{4HQP6doWd zj`{8-#fX-2F@(&_u>2*&^w~xX<6G(q3$3nV5&R+|1b$&*PBp5-)Y$f= zU2Vs94O2EMDk|^Oc(bA0PmtFj zowXmClGO9c^l7A~Jt8yn@{;Zc9Rw4a@cE>CE0%BHzsLU?8$)d$2Om>VP%PINC8qRP z57~-c%(P3@;wxNl-rlGimLK``OaJ_MIP7dI0onM;b6i>N+xdz#;wX7 zr4a>NWcbOQ2P?X&?2~CHDk|!E`riqh0VO<;a+^MSi(7B|b4Wtb(a}kD?0jWUamhhcUzFuz z@t}~xVdR;1o&b2ZYK#O^WAR30wAFNrktWH!(PJTobVxY=GjNg)E4oWdfkb-t3pMaBE-nTTT8Tq=S}bUiX zyZ+B#Ec;8@)6$ZlOOHoiDRNof^IH05=;Y+29lT#|(dKS#tsK{5T|KpVOVWMzWYcx( zGlz7@zrBCpF%t!gw0f=Z{o+M#>i*hhE0&x<?M9opcz%^~J4uwWK1AH_0)FS~HDr zz@FIN+S*FeM_#kPlWA|aHwYttVOOD(FH=WU5EeiCBej{w&Wl>iUj4%GgO0)=`DuH{ z+CM_DqvH(j8tU*7h6aU8)z@E|s5rte7j(v_DeDK+et8k+al02*e0~ugX+sfN@cX3P zqTt_7OYfX6a+4Z`d-5_XB}r;7kxD}1!^e-UfPnRpJzbF(Is*QDiL)rxD{G2VEt1N3 z$So^N@&U+OSK|10Ys;LGmikf7n>Pxq^f7f%?#6@P&KB&ftgQV*L!1W4YoI0OTKov3 zNl8fxI`8#_HPg@lb^&8Qt#D*B%IsaXv6KWR{VY#ZS6?HuCk|e*?&-(>C-L zlpK7+KN6`6K?~)6$*UvBqmwUi*Gl8%P1pSN>62m_@8#DsaW5xn9zJ&`z9+~} z9d#-6FlN_m!};zii5Z(w{GjXnQhPCr|A5-s6YF^8vLU0b$pF8H^gQF>Yn!@m*BY)u z%-CT2$W1w{mX6OASg|;ABQJJIf|j=O^ebWZWN=|D<5Z9iTz2g8j9!3JMA});;kSrWFP@E-r#~@7}#@udm-n+luws zIygMI$lXBM}1+oUCj}euYjy*UySRL8duPTnlS|wmGdaf*zO~U7 zfM6=Xrj{*neD(35p{2MqY$cxRA-}t|Qy@V)x%RkSmo_Pxhbal|-n5)4B7d@tWq0p5 zJ-`F=Rrf*lg5p;ojhni=B9YhnvqZvr7IzYza?l~9gAgL%`h5(>dZ9a-U;reDnw$(l zI|{0K+%$CW-Sv>l_VzQ080_V^-bLU`3g;ZUjO&>q7Mx(2!BPJHjXw#8SO95@(#s5l z$2nFkt7Y#RxuBZLP>_-`>FDXrpX%v##}>T?WS@N;ki0nWBLnF6MjG!9eT>R~fmRy+ z^~VpGc7c47U4N$43ReuQ+s?tEmr^OVcX3Cs3U?`a5g{j+*xjwXEk}S-k_Sk>afL%D zm0n6bUeqglbvxtXV-X2!^>v4aDLZhRSlQTe@cV(>@jR-!QNV&r9M4?=l!N8ZdO&fh zrTeP4YI2Y5$;(y6oKOi`BWe1!k!LG)c;S<&M}t{#jx#Rl?ze-4m|{oEi%LNr9|PSV zts5k3aoDW+BYu`EryoAFWI3|l*>Jt3?RpP4Mt4)}Md89ibGczvWm$Q-GZ37Um4Ex| zerwGjT8WB_>x)X1g)F1l-6kj?p&bhDwzkEc)-|2$`|ajtX1SD|dxwWrn!H!8`TF_> zWeKAK@oQt{b09uoFlj3*E9>9Ce;+auWa5C#2Ci3#n6>)v7^vyGT)ldAOCg|+6}=PK z<_i4B;VBS%YU&mFy&o!7K&m&F4b20VLs2-*e`M@vvbxE{pFj0pWo90LtT?#3xq13& zYExZ~^Fn_uAU&Wq4bxticr}4_z$jl>GOl{tdq1Qj>_)#mnSowA6P#wqN!bWK-{6 z2-41%J8sI&&CO3tOuXDNM_87ok5eV5qM|~r8oX_94?P@t_dr2GMkc4+kxk&v9T6c^ z^PWUP4|(aR<7|yhZzNcM6Z0oeemFKv^`g;ejC3+Zf95WS0UtNi*CPQQ8AyRm z7EZq{=gxvw0vR5I>2_;)_u&H+gUL5;@>+H`_g{#9ppz>ts%L6SY9F*uc&$~ErpU#` zjvmQxSBT)+21A~a{dF8+x;=#Ct#H)E5UOWxepVL|5iv2UqkuZ@x^R6%P(Z*5{NDSN z5CHnO)N~U&PImhle&KK_Yt5X2tM9YKLgeRMn=9`M_Oli7v)wWHI1#e+EmbH*ZugrA zuFB$km_Eh^aV4%%1l8#bgw)g5rusmpwZK|k-UF8x}GQQuuH}2=saEB=+%Sx%C9Ldb^HBkb+spf`MM}Aw()Q_sAI#ciSz#R zjR}X7&<-IOR1nxN+KTJOjT;MIP3mO81ii(wwX*V3RC&Jj_sc#%KRv8+cXVu$fYUp? z*5d2K6EisFgOBKyp$pR5lG$2M7^!NEXzlCn)dvt)-0#HmuNOUqEu9;2X`Nc*5x zxgd=*TV4MV)Re5>)`=sSLhVdXPp5iF=iV0+6YE{@Q1wAM@MH!^+39o>h*MJHFp|zfJIRE zdNO-^dGP@)x(3lRFc{Z{j__*Mx&a+jVBnDPk?pVb-|o85APfrHP>?Bd%qf~bo`r)W zdeHtVSUOj4Z=xO&8QtC8J+!;K%fPF-c6c0Yjzlu!e*J2-k$iLOB=p>tz}qhYa%MrS zDvxj#Zc6vb6Aw9A*&w+#Z~km8XTOQ`0P}$gYz=fBw(|jRV2G-et13VZh#- zH(RSjpM>qk+F!C3iAD28`H1&R4sPGxMe!%9D*L zDdEF`89~_O$cU~`f32O1%Rmo;RuV+7Ph(CTdW=-|b*%8-+tJa{u5!Z-#)3?MsX#O; zD&pDO+bcFSEm`;^+-FD>9!nrs%+636}DqYVo!F>?X- zTx^44-h#ZS3o7B3Vs>QNaNj=lK#mKDw<^6$q*Xt0Y`7H!hsW2u85?;^kyUa+GbsUCfe#1f|jCg z@*~pFu)!6mB}q7|{8k%}czWgf=(0YeU7(@fzgr1&ifZ8%J4?Y1^$mM%e$9by^k1%WraGisd_e6HqP6is z*sH0z6dZX4x4mR!?$oUWBbp3|q!;}J)^yX!#J%-_4wf$nTEXvqZTcDa@sqKy*2d4i zd`N*sfU&fM^SB~%Y-DF=hXknRJEam=jnT*V)z#b8J=SskwQ}pGt@1u%7o^bixVG_U}U-bWZI( Date: Tue, 21 Nov 2017 11:13:46 +0800 Subject: [PATCH 46/53] fix wrong url link. url link should update. --- docs/getting-started-guides/ovirt.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started-guides/ovirt.md b/docs/getting-started-guides/ovirt.md index 325a74882f..93192e26d0 100644 --- a/docs/getting-started-guides/ovirt.md +++ b/docs/getting-started-guides/ovirt.md @@ -22,8 +22,8 @@ It is mandatory to [install the ovirt-guest-agent] in the guests for the VM ip a Once the Kubernetes template is available it is possible to start instantiating VMs that can be discovered by the cloud provider. [import]: http://ovedou.blogspot.it/2014/03/importing-glance-images-as-ovirt.html -[install]: http://www.ovirt.org/Quick_Start_Guide#Create_Virtual_Machines -[generate a template]: http://www.ovirt.org/Quick_Start_Guide#Using_Templates +[install]: https://www.ovirt.org/documentation/quickstart/quickstart-guide/#create-virtual-machines +[generate a template]: https://www.ovirt.org/documentation/quickstart/quickstart-guide/#using-templates [install the ovirt-guest-agent]: http://www.ovirt.org/documentation/how-to/guest-agent/install-the-guest-agent-in-fedora/ ## Using the oVirt Cloud Provider From 7a4e8d540425cb5ec944afa287956f79c590cee5 Mon Sep 17 00:00:00 2001 From: stewart-yu Date: Tue, 21 Nov 2017 11:38:00 +0800 Subject: [PATCH 47/53] fix redirects --- _redirects | 1 + 1 file changed, 1 insertion(+) diff --git a/_redirects b/_redirects index 92eb317983..fd5e5ccce4 100644 --- a/_redirects +++ b/_redirects @@ -418,6 +418,7 @@ https://kubernetes-io-v1-7.netlify.com/* https://v1-7.docs.kubernetes.io/"spl /docs/admin/kube-scheduler/ /docs/reference/generated/kube-scheduler/ 301 /docs/admin/kube-scheduler/ /docs/reference/generated/kube-scheduler/ 301 /docs/admin/kubeadm/ /docs/reference/generated/kubeadm/ 301 +/docs/admin/kubelet/ /docs/reference/generated/kubelet/ 301 /docs/admin/federation-controller-manager/ /docs/reference/generated/federation-controller-manager/ 301 /docs/admin/federation-apiserver/ /docs/reference/generated/federation-apiserver/ 301 /docs/admin/kubefed/ /docs/reference/generated/kubefed/ 301 From b877d1219fe967031d12c0c6c754e29744f3fd25 Mon Sep 17 00:00:00 2001 From: stewart-yu Date: Tue, 21 Nov 2017 13:50:17 +0800 Subject: [PATCH 48/53] fix dead link --- docs/tasks/administer-federation/ingress.md | 2 +- docs/tasks/federation/federation-service-discovery.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tasks/administer-federation/ingress.md b/docs/tasks/administer-federation/ingress.md index 4e312c4e70..5e445e08d2 100644 --- a/docs/tasks/administer-federation/ingress.md +++ b/docs/tasks/administer-federation/ingress.md @@ -300,6 +300,6 @@ Check that: {% capture whatsnext %} * If you need assistance, use one of the [support channels](/docs/tasks/debug-application-cluster/troubleshooting/) to seek assistance. * For details about use cases that motivated this work, see - [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation/federation.md). + [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/multicluster/federation.md). {% endcapture %} {% include templates/task.md %} diff --git a/docs/tasks/federation/federation-service-discovery.md b/docs/tasks/federation/federation-service-discovery.md index e5dc9b47e8..813fa04da4 100644 --- a/docs/tasks/federation/federation-service-discovery.md +++ b/docs/tasks/federation/federation-service-discovery.md @@ -380,4 +380,4 @@ Check that: ## For more information - * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation/federation.md) details use cases that motivated this work. + * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/multicluster/federation.md) details use cases that motivated this work. From 66350ad1f24361ab9f8bc484787c271f82ab8f8d Mon Sep 17 00:00:00 2001 From: Sam Clinckspoor Date: Tue, 21 Nov 2017 14:17:32 +0100 Subject: [PATCH 49/53] Fix links to Node auth and NodeRestrictions --- docs/admin/authorization/rbac.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/admin/authorization/rbac.md b/docs/admin/authorization/rbac.md index 85963009cf..f387f44456 100644 --- a/docs/admin/authorization/rbac.md +++ b/docs/admin/authorization/rbac.md @@ -463,9 +463,7 @@ The permissions required by individual control loops are contained in the system:node None in 1.8+ Allows access to resources required by the kubelet component, including read access to all secrets, and write access to all pod status objects. -As of 1.7, use of the [Node authorizer](/docs/admin/authorization/node/) -and [NodeRestriction admission plugin](/docs/admin/admission-controllers#NodeRestriction) -is recommended instead of this role, and allow granting API access to kubelets based on the pods scheduled to run on them. +As of 1.7, use of the Node authorizer and NodeRestriction admission plugin is recommended instead of this role, and allow granting API access to kubelets based on the pods scheduled to run on them. Prior to 1.7, this role was automatically bound to the `system:nodes` group. In 1.7, this role was automatically bound to the `system:nodes` group if the `Node` authorization mode is not enabled. In 1.8+, no binding is automatically created. From 52b915608ddd8dc1457f3266d8edd8c45c9e1885 Mon Sep 17 00:00:00 2001 From: Colby Scotta Date: Tue, 21 Nov 2017 11:23:51 -0500 Subject: [PATCH 50/53] IBM Bluemix was renamed to IBM Cloud recently --- _data/setup.yml | 6 +++--- docs/setup/pick-right-solution.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/_data/setup.yml b/_data/setup.yml index b1b0106881..d2907e9433 100644 --- a/_data/setup.yml +++ b/_data/setup.yml @@ -23,8 +23,8 @@ toc: path: https://cloud.google.com/kubernetes-engine/docs/before-you-begin/ - title: Running Kubernetes on Azure Container Service path: https://docs.microsoft.com/en-us/azure/container-service/container-service-kubernetes-walkthrough - - title: Running Kubernetes on IBM Bluemix Container Service - path: https://console.ng.bluemix.net/docs/containers/container_index.html + - title: Running Kubernetes on IBM Cloud Container Service + path: https://console.bluemix.net/docs/containers/container_index.html - title: Turn-key Cloud Solutions section: @@ -33,7 +33,7 @@ toc: - docs/getting-started-guides/azure.md - docs/getting-started-guides/alibaba-cloud.md - docs/getting-started-guides/clc.md - - title: Running Kubernetes on IBM Bluemix + - title: Running Kubernetes on IBM Cloud path: https://github.com/patrocinio/kubernetes-softlayer - docs/getting-started-guides/stackpoint.md diff --git a/docs/setup/pick-right-solution.md b/docs/setup/pick-right-solution.md index d823609725..2c9c7844c1 100644 --- a/docs/setup/pick-right-solution.md +++ b/docs/setup/pick-right-solution.md @@ -55,7 +55,7 @@ a Kubernetes cluster from scratch. * [OpenShift Online](https://www.openshift.com/features/) provides free hosted access for Kubernetes applications. -* [IBM Bluemix Container Service](https://console.ng.bluemix.net/docs/containers/container_index.html) offers managed Kubernetes clusters with isolation choice, operational tools, integrated security insight into images and containers, and integration with Watson, IoT, and data. +* [IBM Cloud Container Service](https://console.bluemix.net/docs/containers/container_index.html) offers managed Kubernetes clusters with isolation choice, operational tools, integrated security insight into images and containers, and integration with Watson, IoT, and data. * [Giant Swarm](https://giantswarm.io/product/) offers managed Kubernetes clusters in their own datacenter, on-premises, or on public clouds. @@ -70,7 +70,7 @@ few commands. These solutions are actively developed and have active community s * [Azure](/docs/getting-started-guides/azure/) * [Tectonic by CoreOS](https://coreos.com/tectonic) * [CenturyLink Cloud](/docs/getting-started-guides/clc/) -* [IBM Bluemix](https://github.com/patrocinio/kubernetes-softlayer) +* [IBM Cloud](https://github.com/patrocinio/kubernetes-softlayer) * [Stackpoint.io](/docs/getting-started-guides/stackpoint/) * [KUBE2GO.io](https://kube2go.io/) * [Madcore.Ai](https://madcore.ai/) From bb0d2771c47413d5fbcff153463c0c19dc469a76 Mon Sep 17 00:00:00 2001 From: Andrew Chen Date: Tue, 21 Nov 2017 14:52:25 -0800 Subject: [PATCH 51/53] Service Catalog docs (#5867) * Service Catalog docs (+16 squashed commits) Squashed commits: [765e81d] rework install-service-catalog.md [d81f799] tweak diagrams [b7a3da7] Add tooltips [3b256c5] more rework [828000e] architecture diagram redux [0b809d5] rework [7829301] Outline provision-bind-external-service.md w/ filler text [144fbb3] install service catalog v1 [47b5be4] Reorder images and bullet points [fb577ae] Update What's Next links [8ac984c] Include snippet for install and provision docs [c2eeece] Add Install Service Catalog doc [a84df64] Add hard line break [7fb12c6] Add task [75c46d3] Add List, Provision, and Bind diagrams [6386feb] Service Catalog concept doc * Add install-service-catalog-using-helm * switch mysql examples to message queuing instead * Incorporate feedback * incorporate additional feedback * Incorporate tech review feedback --- _data/concepts.yml | 1 + _data/glossary/managed-service.yaml | 9 + _data/glossary/service-broker.yaml | 9 + _data/glossary/service-catalog.yaml | 8 + _data/tasks.yml | 4 +- docs/concepts/service-catalog/index.md | 234 ++++++++++++++++++ .../install-service-catalog-using-helm.md | 100 ++++++++ .../install-service-catalog-using-sc.md | 77 ++++++ images/docs/service-catalog-architecture.svg | 138 +++++++++++ images/docs/service-catalog-bind.svg | 115 +++++++++ images/docs/service-catalog-list.svg | 136 ++++++++++ images/docs/service-catalog-map.svg | 100 ++++++++ images/docs/service-catalog-provision.svg | 125 ++++++++++ 13 files changed, 1055 insertions(+), 1 deletion(-) create mode 100644 _data/glossary/managed-service.yaml create mode 100644 _data/glossary/service-broker.yaml create mode 100644 _data/glossary/service-catalog.yaml create mode 100644 docs/concepts/service-catalog/index.md create mode 100644 docs/tasks/service-catalog/install-service-catalog-using-helm.md create mode 100644 docs/tasks/service-catalog/install-service-catalog-using-sc.md create mode 100644 images/docs/service-catalog-architecture.svg create mode 100644 images/docs/service-catalog-bind.svg create mode 100644 images/docs/service-catalog-list.svg create mode 100644 images/docs/service-catalog-map.svg create mode 100644 images/docs/service-catalog-provision.svg diff --git a/_data/concepts.yml b/_data/concepts.yml index 8eaab9e39e..1051266be0 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -33,6 +33,7 @@ toc: - docs/concepts/cluster-administration/network-plugins.md - docs/concepts/cluster-administration/device-plugins.md - docs/concepts/cluster-administration/sysctl-cluster.md + - docs/concepts/service-catalog/index.md - title: Containers section: diff --git a/_data/glossary/managed-service.yaml b/_data/glossary/managed-service.yaml new file mode 100644 index 0000000000..409831141f --- /dev/null +++ b/_data/glossary/managed-service.yaml @@ -0,0 +1,9 @@ +id: managed-service +name: Managed Service +tags: +- extension +short-description: > + A software offering maintained by a third-party provider. +long-description: > + Some examples of Managed Services are AWS EC2, Azure SQL Database, and GCP Pub/Sub, but they can be any software offering that can be used by an application. + [Service Catalog](/docs/concepts/service-catalog/) provides a way to list, provision, and bind with Managed Services offered by {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}. \ No newline at end of file diff --git a/_data/glossary/service-broker.yaml b/_data/glossary/service-broker.yaml new file mode 100644 index 0000000000..9cdc99bbcb --- /dev/null +++ b/_data/glossary/service-broker.yaml @@ -0,0 +1,9 @@ +id: service-broker +name: Service Broker +tags: +- extension +short-description: > + An endpoint for a set of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered and maintained by a third-party. +long-description: > + {% glossary_tooltip text="Service Brokers" term_id="service-broker" %} implement the [Open Service Broker API spec](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md) and provide a standard interface for applications to use their Managed Services. + [Service Catalog](/docs/concepts/service-catalog/) provides a way to list, provision, and bind with Managed Services offered by Service Brokers. \ No newline at end of file diff --git a/_data/glossary/service-catalog.yaml b/_data/glossary/service-catalog.yaml new file mode 100644 index 0000000000..bcbadd309c --- /dev/null +++ b/_data/glossary/service-catalog.yaml @@ -0,0 +1,8 @@ +id: service-catalog +name: Service Catalog +tags: +- extension +short-description: > + An extension API that enables applications running in Kubernetes clusters to easily use external managed software offerings, such as a datastore service offered by a cloud provider. +long-description: > + Service Catalog provides a way to list, provision, and bind with external {% glossary_tooltip text="Managed Services" term_id="managed-service" %} from {% glossary_tooltip text="Service Brokers" term_id="service-broker" %} without needing detailed knowledge about how those services are created or managed. \ No newline at end of file diff --git a/_data/tasks.yml b/_data/tasks.yml index 4820d91855..15eb64620b 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -100,7 +100,7 @@ toc: - title: Use Explorer to Examine the Runtime Environment path: https://github.com/kubernetes/kubernetes/tree/release-1.5/examples/explorer -- title: Access and Extend the Kubernetes API +- title: Extend Kubernetes section: - docs/tasks/access-kubernetes-api/http-proxy-access-api.md - docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md @@ -108,6 +108,8 @@ toc: - docs/tasks/access-kubernetes-api/migrate-third-party-resource.md - docs/tasks/access-kubernetes-api/configure-aggregation-layer.md - docs/tasks/access-kubernetes-api/setup-extension-api-server.md + - docs/tasks/service-catalog/install-service-catalog-using-helm.md + - docs/tasks/service-catalog/install-service-catalog-using-sc.md - title: TLS section: diff --git a/docs/concepts/service-catalog/index.md b/docs/concepts/service-catalog/index.md new file mode 100644 index 0000000000..bf98efe9c5 --- /dev/null +++ b/docs/concepts/service-catalog/index.md @@ -0,0 +1,234 @@ +--- +title: Service Catalog +approvers: +- chenopis +--- + +{% capture overview %} +{% glossary_definition term_id="service-catalog" length="all" prepend="Service Catalog is " %} + +A *Service Broker*, as defined by the [Open Service Broker API spec](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker/blob/v2.13/spec.md), is an endpoint for a set of Managed Services offered and maintained by a third-party, which could be a cloud provider such as AWS, GCP, or Azure. +Some examples of *Managed Services* are Microsoft Azure Cloud Queue, Amazon Simple Queue Service, and Google Cloud Pub/Sub, but they can be any software offering that can be used by an application. + +Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered by a {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster. + +{% endcapture %} + + +{% capture body %} +## Example use case + +An {% glossary_tooltip text="Application Developer" term_id="application-developer" %} wants to use message queuing as part of their application running in a Kubernetes cluster. +However, they do not want to deal with the overhead of setting such a service up and administering it themselves. +Fortunately, there is a cloud provider that offers message queuing as a *Managed Service* through their *Service Broker*. + +A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can setup Service Catalog and use it to communicate with the cloud provider's {% glossary_tooltip text="Service Broker" term_id="service-broker" %} to provision an instance of the message queuing service and make it available to the application within the Kubernetes cluster. +The {% glossary_tooltip text="Application Developer" term_id="application-developer" %} therefore does not need to concern themselves with the implementation details or management of the message queue. +Their application can simply use it as a service. + +## Architecture + +Service Catalog uses the [Open Service Broker API](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker) to communicate with Service Brokers, acting as an intermediary for the Kubernetes API Server in order to negotiate the initial provisioning and retrieve the credentials necessary for the application to use a Managed Service. + +It is implemented as an extension API server and a controller manager, using Etcd for storage. It also uses the [aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) available in Kubernetes 1.7+ to present its API. + +
+ +![Service Catalog Architecture](/images/docs/service-catalog-architecture.svg) + + +### API Resources + +Service Catalog installs the `servicecatalog.k8s.io` API and provides the following Kubernetes resources: + +* `ClusterServiceBroker`: An in-cluster representation of a Service Broker, encapsulating its server connection details. +These are created and managed by Cluster Operators who wish to use that broker server to make new types of Managed Services available within their cluster. +* `ClusterServiceClass`: A Managed Service offered by a particular Service Broker. +When a new `ClusterServiceBroker` resource is added to the cluster, the Service Catalog controller connects to the Service Broker to obtain a list of available Managed Services. It then creates a new `ClusterServiceClass` resource corresponding to each Managed Service. +* `ClusterServicePlan`: A specific offering of a Managed Service. For example, a Managed Service may have different plans available, such as a free tier or paid tier, or it may have different configuration options, such as using SSD storage or having more resources. Similar to `ClusterServiceClass`, when a new `ClusterServiceBroker` is added to the cluster, the Service Catalog creates a new `ClusterServicePlan` resource corresponding to each Service Plan available for each Managed Service. +* `ServiceInstance`: A provisioned instance of a `ClusterServiceClass`. +These are created by Cluster Operators to make a specific instance of a Managed Service available for use by one or more in-cluster applications. +When a new `ServiceInstance` resource is created, the Service Catalog controller will connect to the appropriate Service Broker and instruct it to provision the service instance. +* `ServiceBinding`: Access credentials to a `ServiceInstance`. +These are created by Cluster Operators who want their applications to make use of a Service `ServiceInstance`. +Upon creation, the Service Catalog controller will create a Kubernetes `Secret` containing connection details and credentials for the Service Instance, which can be mounted into Pods. + +### Authentication + +Service Catalog supports these methods of authentication: + +* Basic (username/password) +* [OAuth 2.0 Bearer Token](https://tools.ietf.org/html/rfc6750) + +## Usage + +A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can use the Service Catalog API Resources to provision Managed Services and make them available within a Kubernetes cluster. The steps involved are: + +1. Listing the Managed Services and Service Plans available from a Service Broker. +1. Provisioning a new instance of the Managed Service. +1. Binding to the Managed Service, which returns the connection credentials. +1. Mapping the connection credentials into the application. + +### Listing Managed Services and Service Plans + +First, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} must create a `ClusterServiceBroker` resource within the `servicecatalog.k8s.io` group. This resource contains the URL and connection details necessary to access a Service Broker endpoint. + +This is an example of a `ClusterServiceBroker` resource: + +```yaml +apiVersion: servicecatalog.k8s.io/v1beta1 +kind: ClusterServiceBroker +metadata: + name: cloud-broker +spec: + # Points to the endpoint of a Service Broker. (This example is not a working URL.) + url: https://servicebroker.somecloudprovider.com/v1alpha1/projects/service-catalog/brokers/default + ##### + # Additional values can be added here, which may be used to communicate + # with the Service Broker, such as bearer token info or a caBundle for TLS. + ##### +``` + +The following is a sequence diagram illustrating the steps involved in listing Managed Services and Plans available from a Service Broker: + +![List Services](/images/docs/service-catalog-list.svg){:height="80%" width="80%"} + +1. Once the `ClusterServiceBroker` resource is added to Service Catalog, it triggers a *List Services* call to the external Service Broker. +1. The Service Broker returns a list of available Managed Services and Service Plans, which are cached locally in `ClusterServiceClass` and `ClusterServicePlan` resources. +1. A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can then get the list of available Managed Services using the following command: + + kubectl get clusterserviceclasses -o=custom-columns=SERVICE\ NAME:.metadata.name,EXTERNAL\ NAME:.spec.externalName + + It should output a list of service names with a format similar to: + + SERVICE NAME EXTERNAL NAME + 4f6e6cf6-ffdd-425f-a2c7-3c9258ad2468 cloud-provider-service + ... ... + + They can also view the Service Plans available using the following command: + + kubectl get clusterserviceplans -o=custom-columns=PLAN\ NAME:.metadata.name,EXTERNAL\ NAME:.spec.externalName + + It should output a list of plan names with a format similar to: + + PLAN NAME EXTERNAL NAME + 86064792-7ea2-467b-af93-ac9694d96d52 service-plan-name + ... ... + + +### Provisioning a new instance + +A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can initiate the provisioning of a new instance by creating a `ServiceInstance` resource. + +This is an example of a `ServiceInstance` resource: + +```yaml +apiVersion: servicecatalog.k8s.io/v1beta1 +kind: ServiceInstance +metadata: + name: cloud-queue-instance + namespace: cloud-apps +spec: + # References one of the previously returned services + clusterServiceClassExternalName: cloud-provider-service + clusterServicePlanExternalName: service-plan-name + ##### + # Additional parameters can be added here, + # which may be used by the Service Broker. + ##### +``` + +The following sequence diagram illustrates the steps involved in provisioning a new instance of a Managed Service: + +![Provision a Service](/images/docs/service-catalog-provision.svg){:height="80%" width="80%"} + +1. When the `ServiceInstance` resource is created, Service Catalog initiates a *Provision Instance* call to the external Service Broker. +1. The Service Broker creates a new instance of the Managed Service and returns an HTTP response. +1. A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can then check the status of the instance to see if it is ready. + +### Binding to a Managed Service + +After a new instance has been provisioned, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} must bind to the Managed Service to get the connection credentials and service account details necessary for the application to use the service. This is done by creating a `ServiceBinding` resource. + +The following is an example of a `ServiceBinding` resource: + +```yaml +apiVersion: servicecatalog.k8s.io/v1beta1 +kind: ServiceBinding +metadata: + name: cloud-queue-binding + namespace: cloud-apps +spec: + instanceRef: + name: cloud-queue-instance + ##### + # Additional information can be added here, such as a secretName or + # service account parameters, which may be used by the Service Broker. + ##### +``` + +The following sequence diagram illustrates the steps involved in binding to a Managed Service instance: + +![Bind to a Managed Service](/images/docs/service-catalog-bind.svg){:height="80%" width="80%"} + +1. After the `ServiceBinding` is created, Service Catalog makes a *Bind Instance* call to the external Service Broker. +1. The Service Broker enables the application permissions/roles for the appropriate service account. +1. The Service Broker returns the information necessary to connect and access the Managed Service instance. This is provider and service-specific so the information returned may differ between Service Providers and their Managed Services. + +### Mapping the connection credentials + +After binding, the final step involves mapping the connection credentials and service-specific information into the application. +These pieces of information are stored in secrets that the application in the cluster can access and use to connect directly with the Managed Service. + +
+ +![Map connection credentials](/images/docs/service-catalog-map.svg) + +#### Pod Configuration File + +One method to perform this mapping is to use a declarative Pod configuration. + +The following example describes how to map service account credentials into the application. A key called `sa-key` is stored in a volume named `provider-cloud-key`, and the application mounts this volume at `/var/secrets/provider/key.json`. The environment variable `GOOGLE_APPLICATION_CREDENTIALS` is mapped from the value of the mounted file. + +```yaml +... + spec: + volumes: + - name: provider-cloud-key + secret: + secretName: sa-key + containers: +... + volumeMounts: + - name: provider-cloud-key + mountPath: /var/secrets/provider + env: + - name: PROVIDER_APPLICATION_CREDENTIALS + value: "/var/secrets/provider/key.json" +``` + +The following example describes how to map secret values into application environment variables. In this example, the messaging queue topic name is mapped from a secret named `provider-queue-credentials` with a key named `topic` to the environment variable `TOPIC`. + + +```yaml +... + env: + - name: "TOPIC" + valueFrom: + secretKeyRef: + name: provider-queue-credentials + key: topic +``` + +{% endcapture %} + + +{% capture whatsnext %} +* If you are familiar with {% glossary_tooltip text="Helm Charts" term_id="helm-chart" %}, [install Service Catalog using Helm](/docs/tasks/service-catalog/install-service-catalog-using-helm/) into your Kubernetes cluster. Alternatively, you can [install Service Catalog using the SC tool](/docs/tasks/service-catalog/install-service-catalog-using-sc/). +* View [sample service brokers](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker/blob/master/gettingStarted.md#sample-service-brokers). +* Explore the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog) project. + +{% endcapture %} + + +{% include templates/concept.md %} diff --git a/docs/tasks/service-catalog/install-service-catalog-using-helm.md b/docs/tasks/service-catalog/install-service-catalog-using-helm.md new file mode 100644 index 0000000000..9ce776cb28 --- /dev/null +++ b/docs/tasks/service-catalog/install-service-catalog-using-helm.md @@ -0,0 +1,100 @@ +--- +title: Install Service Catalog using Helm +approvers: +- chenopis +--- + +{% capture overview %} +{% glossary_definition term_id="service-catalog" length="long" %} + +Use [Helm](https://helm.sh/) to install Service Catalog on your Kubernetes cluster. Up to date information on this process can be found at the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog/blob/master/docs/install.md) repo. + +{% endcapture %} + + +{% capture prerequisites %} +* Understand the key concepts of [Service Catalog](/docs/concepts/service-catalog/). +* Service Catalog requires a Kubernetes cluster running version 1.7 or higher. +* You must have a Kubernetes cluster with cluster DNS enabled. + * If you are using a cloud-based Kubernetes cluster or {% glossary_tooltip text="Minikube" term_id="minikube" %}, you may already have cluster DNS enabled. + * If you are using `hack/local-up-cluster.sh`, ensure that the `KUBE_ENABLE_CLUSTER_DNS` environment variable is set, then run the install script. +* [Install and setup kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) v1.7 or higher. Make sure it is configured to connect to the Kubernetes cluster. +* Install [Helm](http://helm.sh/) v2.7.0 or newer. + * Follow the [Helm install instructions](https://github.com/kubernetes/helm/blob/master/docs/install.md). + * If you already have an appropriate version of Helm installed, execute `helm init` to install Tiller, the server-side component of Helm. + +{% endcapture %} + + +{% capture steps %} +## Add the service-catalog Helm repository + +Once Helm is installed, add the *service-catalog* Helm repository to your local machine by executing the following command: + +```shell +helm repo add svc-cat https://svc-catalog-charts.storage.googleapis.com +``` + +Check to make sure that it installed successfully by executing the following command: + +```shell +helm search service-catalog +``` + +If the installation was successful, the command should output the following: + +``` +NAME VERSION DESCRIPTION +svc-cat/catalog 0.0.1 service-catalog API server and controller-manag... +``` + +## Enable RBAC + +Your Kubernetes cluster must have RBAC enabled, which requires your Tiller Pod(s) to have `cluster-admin` access. + +If you are using {% glossary_tooltip text="Minikube" term_id="minikube" %}, run the `minikube start` command with the following flag: + +```shell +minikube start --extra-config=apiserver.Authorization.Mode=RBAC +``` + +If you are using `hack/local-up-cluster.sh`, set the `AUTHORIZATION_MODE` environment variable with the following values: + +``` +AUTHORIZATION_MODE=Node,RBAC hack/local-up-cluster.sh -O +``` + +By default, `helm init` installs the Tiller Pod into the `kube-system` namespace, with Tiller configured to use the `default` service account. + +**NOTE:** If you used the `--tiller-namespace` or `--service-account` flags when running `helm init`, the `--serviceaccount` flag in the following command needs to be adjusted to reference the appropriate namespace and ServiceAccount name. +{: .note} + +Configure Tiller to have `cluster-admin` access: + +```shell +kubectl create clusterrolebinding tiller-cluster-admin \ + --clusterrole=cluster-admin \ + --serviceaccount=kube-system:default +``` + + +## Install Service Catalog in your Kubernetes cluster + +Install Service Catalog from the root of the Helm repository using the following command: + +```shell +helm install svc-cat/catalog \ + --name catalog --namespace catalog +``` + +{% endcapture %} + + +{% capture whatsnext %} +* View [sample service brokers](https://github.com/openservicebrokerapi/servicebroker/blob/master/gettingStarted.md#sample-service-brokers). +* Explore the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog) project. + +{% endcapture %} + + +{% include templates/task.md %} \ No newline at end of file diff --git a/docs/tasks/service-catalog/install-service-catalog-using-sc.md b/docs/tasks/service-catalog/install-service-catalog-using-sc.md new file mode 100644 index 0000000000..e235e0e0ed --- /dev/null +++ b/docs/tasks/service-catalog/install-service-catalog-using-sc.md @@ -0,0 +1,77 @@ +--- +title: Install Service Catalog using SC +approvers: +- chenopis +--- + +{% capture overview %} +{% glossary_definition term_id="service-catalog" length="long" %} + +Use the [Service Catalog Installer](https://github.com/GoogleCloudPlatform/k8s-service-catalog#installation) tool to easily install or uninstall Service Catalog on your Kubernetes cluster. This CLI tool is installed as `sc` in your local environment. + +{% endcapture %} + + +{% capture prerequisites %} +* Understand the key concepts of [Service Catalog](/docs/concepts/service-catalog/). +* Install [Go 1.6+](https://golang.org/dl/) and set the `GOPATH`. +* Install the [cfssl](https://github.com/cloudflare/cfssl) tool needed for generating SSL artifacts. +* Service Catalog requires Kubernetes version 1.7+. +* [Install and setup kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) so that it is configured to connect to a Kubernetes v1.7+ cluster. +* The kubectl user must be bound to the *cluster-admin* role for it to install Service Catalog. To ensure that this is true, run the following command: + + kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user= + +{% endcapture %} + + +{% capture steps %} +## Install `sc` in your local environment + +Install the `sc` CLI tool using the `go get` command: + +```Go +go get github.com/GoogleCloudPlatform/k8s-service-catalog/installer/cmd/sc +``` + +After running the above command, `sc` should be installed in your `GOPATH/bin` directory. + +## Install Service Catalog in your Kubernetes cluster + +First, verify that all dependencies have been installed. Run: + +```shell +sc check +``` + +If the check is successful, it should return: + +``` +Dependency check passed. You are good to go. +``` + +Next, run the install command and specify the `storageclass` that you want to use for the backup: + +```shell +sc install --etcd-backup-storageclass "standard" +``` + +## Uninstall Service Catalog + +If you would like to uninstall Service Catalog from your Kubernetes cluster using the `sc` tool, run: + +```shell +sc uninstall +``` + +{% endcapture %} + + +{% capture whatsnext %} +* View [sample service brokers](https://github.com/openservicebrokerapi/servicebroker/blob/master/gettingStarted.md#sample-service-brokers). +* Explore the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog) project. + +{% endcapture %} + + +{% include templates/task.md %} \ No newline at end of file diff --git a/images/docs/service-catalog-architecture.svg b/images/docs/service-catalog-architecture.svg new file mode 100644 index 0000000000..57c7558d5a --- /dev/null +++ b/images/docs/service-catalog-architecture.svg @@ -0,0 +1,138 @@ + + + + Produced by OmniGraffle 7.5 + 2017-11-17 22:47:47 +0000 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + architecture + + Layer 1 + + + + Service Broker + A + + + + API Server + + + + Service Catalog + servicecatalog.k8s.io: + ClusterServiceBroker + ClusterServiceClass + ClusterServicePlan + ServiceInstance + ServiceBinding + + + + Application + + + + … + + + + Service Broker Z + + + + Managed Service 2 + + + + Managed Service N + + + + Managed Service 1 + + + + Open Service Broker + API + + + List Services + Provision Instance + Bind Instance + + + + + … + + + + + Bind Instance + + + + Secret: + Connection Credentials + Service Details + + + Kubernetes + + + + diff --git a/images/docs/service-catalog-bind.svg b/images/docs/service-catalog-bind.svg new file mode 100644 index 0000000000..0a57f944aa --- /dev/null +++ b/images/docs/service-catalog-bind.svg @@ -0,0 +1,115 @@ + + + + Produced by OmniGraffle 7.5 + 2017-11-17 22:45:14 +0000 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + V2b + + Layer 1 + + + + + + + + + + + + Bind Instance + + + + + Connection + Information + + + + ServiceBinding + Resource + + + + ServiceBinding + Resource + + + + + Service Catalog + API Server + + + + Service Broker + + + + Cluster Operator + + + + + + 1. + + + + + + + 3. + + + + + + Service + + + + + + 2. + + + + + diff --git a/images/docs/service-catalog-list.svg b/images/docs/service-catalog-list.svg new file mode 100644 index 0000000000..ba1802d8fe --- /dev/null +++ b/images/docs/service-catalog-list.svg @@ -0,0 +1,136 @@ + + + + Produced by OmniGraffle 7.5 + 2017-11-17 22:45:14 +0000 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + V2b + + Layer 1 + + + + + + + + + + ClusterServiceClass + Resource + + + + + + + Service Catalog + API Server + + + + Service Broker + + + + List Services + + + + ClusterServiceBroker + Resource + + + + + + Cluster Operator + + + + + + 2. + + + + + + + 3. + + + + + + + 1. + + + + + + List of + Services, + Plans + + + + + ClusterServicePlan + Resource + + + + Services, Plans + + + + get clusterserviceplans + + + + get clusterserviceclasses + + + + diff --git a/images/docs/service-catalog-map.svg b/images/docs/service-catalog-map.svg new file mode 100644 index 0000000000..091cd4efef --- /dev/null +++ b/images/docs/service-catalog-map.svg @@ -0,0 +1,100 @@ + + + + Produced by OmniGraffle 7.5 + 2017-11-07 08:04:59 +0000 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + map creds + + Layer 1 + + + + Service Broker + + + + API Server + + + + Service Catalog + servicecatalog.k8s.io: + ServiceBinding + + + + Application + + + + Managed Service + Instance + + + + Bind Instance + + + Service Account + + + + + + + Secret: + Connection Credentials + Service + Account Details + … + + + Kubernetes + + + + diff --git a/images/docs/service-catalog-provision.svg b/images/docs/service-catalog-provision.svg new file mode 100644 index 0000000000..748ba3a336 --- /dev/null +++ b/images/docs/service-catalog-provision.svg @@ -0,0 +1,125 @@ + + + + Produced by OmniGraffle 7.5 + 2017-11-17 23:02:50 +0000 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + V2b + + Layer 1 + + + + + + + + + + + + Provision Instance + + + + + ServiceInstance + Resource + + + + ServiceInstance + Resource + + + + + + get serviceinstance + + + + + READY + + + + Service Catalog + API Server + + + + Service Broker + + + + Cluster Operator + + + + + + 3. + + + + + + + 1. + + + + + + + 2. + + + + + + Service + + + + From da5fac35badd4af2f2070ddd790206c946fc4ba2 Mon Sep 17 00:00:00 2001 From: Kevin Hoffman Date: Wed, 22 Nov 2017 08:23:12 -0500 Subject: [PATCH 52/53] Update index.md Stale links to service broker specs and documentation. --- docs/concepts/service-catalog/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/concepts/service-catalog/index.md b/docs/concepts/service-catalog/index.md index bf98efe9c5..814505ccb3 100644 --- a/docs/concepts/service-catalog/index.md +++ b/docs/concepts/service-catalog/index.md @@ -7,7 +7,7 @@ approvers: {% capture overview %} {% glossary_definition term_id="service-catalog" length="all" prepend="Service Catalog is " %} -A *Service Broker*, as defined by the [Open Service Broker API spec](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker/blob/v2.13/spec.md), is an endpoint for a set of Managed Services offered and maintained by a third-party, which could be a cloud provider such as AWS, GCP, or Azure. +A *Service Broker*, as defined by the [Open Service Broker API spec](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md), is an endpoint for a set of Managed Services offered and maintained by a third-party, which could be a cloud provider such as AWS, GCP, or Azure. Some examples of *Managed Services* are Microsoft Azure Cloud Queue, Amazon Simple Queue Service, and Google Cloud Pub/Sub, but they can be any software offering that can be used by an application. Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered by a {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster. @@ -28,7 +28,7 @@ Their application can simply use it as a service. ## Architecture -Service Catalog uses the [Open Service Broker API](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker) to communicate with Service Brokers, acting as an intermediary for the Kubernetes API Server in order to negotiate the initial provisioning and retrieve the credentials necessary for the application to use a Managed Service. +Service Catalog uses the [Open Service Broker API](https://github.com/openservicebrokerapi/servicebroker) to communicate with Service Brokers, acting as an intermediary for the Kubernetes API Server in order to negotiate the initial provisioning and retrieve the credentials necessary for the application to use a Managed Service. It is implemented as an extension API server and a controller manager, using Etcd for storage. It also uses the [aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) available in Kubernetes 1.7+ to present its API. @@ -225,7 +225,7 @@ The following example describes how to map secret values into application enviro {% capture whatsnext %} * If you are familiar with {% glossary_tooltip text="Helm Charts" term_id="helm-chart" %}, [install Service Catalog using Helm](/docs/tasks/service-catalog/install-service-catalog-using-helm/) into your Kubernetes cluster. Alternatively, you can [install Service Catalog using the SC tool](/docs/tasks/service-catalog/install-service-catalog-using-sc/). -* View [sample service brokers](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker/blob/master/gettingStarted.md#sample-service-brokers). +* View [sample service brokers](https://github.com/openservicebrokerapi/servicebroker/blob/master/gettingStarted.md#sample-service-brokers). * Explore the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog) project. {% endcapture %} From c5319e204b3192bafe4bfdd9e12bcd964d2c90a8 Mon Sep 17 00:00:00 2001 From: Qiming Date: Thu, 23 Nov 2017 03:47:05 +0800 Subject: [PATCH 53/53] Sort volumes for easier browsing (#6320) --- docs/concepts/storage/volumes.md | 891 ++++++++++++++++--------------- 1 file changed, 455 insertions(+), 436 deletions(-) diff --git a/docs/concepts/storage/volumes.md b/docs/concepts/storage/volumes.md index 4ea6df948a..2d2ad25678 100644 --- a/docs/concepts/storage/volumes.md +++ b/docs/concepts/storage/volumes.md @@ -65,33 +65,118 @@ mount each volume. Kubernetes supports several types of Volumes: - * `emptyDir` - * `hostPath` - * `gcePersistentDisk` * `awsElasticBlockStore` - * `nfs` - * `iscsi` - * `fc (fibre channel)` - * `flocker` - * `glusterfs` - * `rbd` - * `cephfs` - * `gitRepo` - * `secret` - * `persistentVolumeClaim` - * `downwardAPI` - * `projected` - * `azureFileVolume` * `azureDisk` - * `vsphereVolume` - * `Quobyte` - * `PortworxVolume` - * `ScaleIO` - * `StorageOS` + * `azureFile` + * `cephfs` + * `downwardAPI` + * `emptyDir` + * `fc` (fibre channel) + * `flocker` + * `gcePersistentDisk` + * `gitRepo` + * `glusterfs` + * `hostPath` + * `iscsi` * `local` + * `nfs` + * `persistentVolumeClaim` + * `projected` + * `portworxVolume` + * `quobyte` + * `rbd` + * `scaleIO` + * `secret` + * `storageos` + * `vsphereVolume` We welcome additional contributions. +### awsElasticBlockStore + +An `awsElasticBlockStore` volume mounts an Amazon Web Services (AWS) [EBS +Volume](http://aws.amazon.com/ebs/) into your pod. Unlike +`emptyDir`, which is erased when a Pod is removed, the contents of an EBS +volume are preserved and the volume is merely unmounted. This means that an +EBS volume can be pre-populated with data, and that data can be "handed off" +between pods. + +**Important:** You must create an EBS volume using `aws ec2 create-volume` or the AWS API before you can use it. +{: .caution} + +There are some restrictions when using an awsElasticBlockStore volume: + +* the nodes on which pods are running must be AWS EC2 instances +* those instances need to be in the same region and availability-zone as the EBS volume +* EBS only supports a single EC2 instance mounting a volume + +#### Creating an EBS volume + +Before you can use an EBS volume with a pod, you need to create it. + +```shell +aws ec2 create-volume --availability-zone=eu-west-1a --size=10 --volume-type=gp2 +``` + +Make sure the zone matches the zone you brought up your cluster in. (And also check that the size and EBS volume +type are suitable for your use!) + +#### AWS EBS Example configuration + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: test-ebs +spec: + containers: + - image: gcr.io/google_containers/test-webserver + name: test-container + volumeMounts: + - mountPath: /test-ebs + name: test-volume + volumes: + - name: test-volume + # This AWS EBS volume must already exist. + awsElasticBlockStore: + volumeID: + fsType: ext4 +``` + +### azureDisk + +A `azureDisk` is used to mount a Microsoft Azure [Data Disk](https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-linux-about-disks-vhds/) into a Pod. + +More details can be found [here](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/azure_disk/README.md). + +### azureFile + +A `azureFile` is used to mount a Microsoft Azure File Volume (SMB 2.1 and 3.0) +into a Pod. + +More details can be found [here](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/azure_file/README.md). + +### cephfs + +A `cephfs` volume allows an existing CephFS volume to be +mounted into your pod. Unlike `emptyDir`, which is erased when a Pod is +removed, the contents of a `cephfs` volume are preserved and the volume is merely +unmounted. This means that a CephFS volume can be pre-populated with data, and +that data can be "handed off" between pods. CephFS can be mounted by multiple +writers simultaneously. + +**Important:** You must have your own Ceph server running with the share exported before you can use it. +{: .caution} + +See the [CephFS example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/cephfs/) for more details. + +### downwardAPI + +A `downwardAPI` volume is used to make downward API data available to applications. +It mounts a directory and writes the requested data in plain text files. + +See the [`downwardAPI` volume example](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/) for more details. + ### emptyDir An `emptyDir` volume is first created when a Pod is assigned to a Node, and @@ -138,6 +223,132 @@ spec: emptyDir: {} ``` +### fc (fibre channel) + +An `fc` volume allows an existing fibre channel volume to be mounted in a pod. +You can specify single or multiple target World Wide Names using the parameter +`targetWWNs` in your volume configuration. If multiple WWNs are specified, +targetWWNs expect that those WWNs are from multi-path connections. + +**Important:** You must configure FC SAN Zoning to allocate and mask those LUNs (volumes) to the target WWNs beforehand so that Kubernetes hosts can access them. +{: .caution} + +See the [FC example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/fibre_channel) for more details. + +### flocker + +[Flocker](https://clusterhq.com/flocker) is an open-source clustered container data volume manager. It provides management +and orchestration of data volumes backed by a variety of storage backends. + +A `flocker` volume allows a Flocker dataset to be mounted into a pod. If the +dataset does not already exist in Flocker, it needs to be first created with the Flocker +CLI or by using the Flocker API. If the dataset already exists it will be +reattached by Flocker to the node that the pod is scheduled. This means data +can be "handed off" between pods as required. + +**Important:** You must have your own Flocker installation running before you can use it. +{: .caution} + +See the [Flocker example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/flocker) for more details. + +### gcePersistentDisk + +A `gcePersistentDisk` volume mounts a Google Compute Engine (GCE) [Persistent +Disk](http://cloud.google.com/compute/docs/disks) into your pod. Unlike +`emptyDir`, which is erased when a Pod is removed, the contents of a PD are +preserved and the volume is merely unmounted. This means that a PD can be +pre-populated with data, and that data can be "handed off" between pods. + +**Important:** You must create a PD using `gcloud` or the GCE API or UI before you can use it. +{: .caution} + +There are some restrictions when using a `gcePersistentDisk`: + +* the nodes on which pods are running must be GCE VMs +* those VMs need to be in the same GCE project and zone as the PD + +A feature of PD is that they can be mounted as read-only by multiple consumers +simultaneously. This means that you can pre-populate a PD with your dataset +and then serve it in parallel from as many pods as you need. Unfortunately, +PDs can only be mounted by a single consumer in read-write mode - no +simultaneous writers allowed. + +Using a PD on a pod controlled by a ReplicationController will fail unless +the PD is read-only or the replica count is 0 or 1. + +#### Creating a PD + +Before you can use a GCE PD with a pod, you need to create it. + +```shell +gcloud compute disks create --size=500GB --zone=us-central1-a my-data-disk +``` + +#### Example pod + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: test-pd +spec: + containers: + - image: gcr.io/google_containers/test-webserver + name: test-container + volumeMounts: + - mountPath: /test-pd + name: test-volume + volumes: + - name: test-volume + # This GCE PD must already exist. + gcePersistentDisk: + pdName: my-data-disk + fsType: ext4 +``` + +### gitRepo + +A `gitRepo` volume is an example of what can be done as a volume plugin. It +mounts an empty directory and clones a git repository into it for your pod to +use. In the future, such volumes may be moved to an even more decoupled model, +rather than extending the Kubernetes API for every such use case. + +Here is an example for gitRepo volume: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: server +spec: + containers: + - image: nginx + name: nginx + volumeMounts: + - mountPath: /mypath + name: git-volume + volumes: + - name: git-volume + gitRepo: + repository: "git@somewhere:me/my-git-repository.git" + revision: "22f1d8406d464b0c0874075539c1f2e96c253775" +``` + +### glusterfs + +A `glusterfs` volume allows a [Glusterfs](http://www.gluster.org) (an open +source networked filesystem) volume to be mounted into your pod. Unlike +`emptyDir`, which is erased when a Pod is removed, the contents of a +`glusterfs` volume are preserved and the volume is merely unmounted. This +means that a glusterfs volume can be pre-populated with data, and that data can +be "handed off" between pods. GlusterFS can be mounted by multiple writers +simultaneously. + +**Important:** You must have your own GlusterFS installation running before you can use it. +{: .caution} + +See the [GlusterFS example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/glusterfs) for more details. + ### hostPath A `hostPath` volume mounts a file or directory from the host node's filesystem @@ -202,126 +413,6 @@ spec: type: Directory ``` -### gcePersistentDisk - -A `gcePersistentDisk` volume mounts a Google Compute Engine (GCE) [Persistent -Disk](http://cloud.google.com/compute/docs/disks) into your pod. Unlike -`emptyDir`, which is erased when a Pod is removed, the contents of a PD are -preserved and the volume is merely unmounted. This means that a PD can be -pre-populated with data, and that data can be "handed off" between pods. - -**Important:** You must create a PD using `gcloud` or the GCE API or UI before you can use it. -{: .caution} - -There are some restrictions when using a `gcePersistentDisk`: - -* the nodes on which pods are running must be GCE VMs -* those VMs need to be in the same GCE project and zone as the PD - -A feature of PD is that they can be mounted as read-only by multiple consumers -simultaneously. This means that you can pre-populate a PD with your dataset -and then serve it in parallel from as many pods as you need. Unfortunately, -PDs can only be mounted by a single consumer in read-write mode - no -simultaneous writers allowed. - -Using a PD on a pod controlled by a ReplicationController will fail unless -the PD is read-only or the replica count is 0 or 1. - -#### Creating a PD - -Before you can use a GCE PD with a pod, you need to create it. - -```shell -gcloud compute disks create --size=500GB --zone=us-central1-a my-data-disk -``` - -#### Example pod - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: test-pd -spec: - containers: - - image: gcr.io/google_containers/test-webserver - name: test-container - volumeMounts: - - mountPath: /test-pd - name: test-volume - volumes: - - name: test-volume - # This GCE PD must already exist. - gcePersistentDisk: - pdName: my-data-disk - fsType: ext4 -``` - -### awsElasticBlockStore - -An `awsElasticBlockStore` volume mounts an Amazon Web Services (AWS) [EBS -Volume](http://aws.amazon.com/ebs/) into your pod. Unlike -`emptyDir`, which is erased when a Pod is removed, the contents of an EBS -volume are preserved and the volume is merely unmounted. This means that an -EBS volume can be pre-populated with data, and that data can be "handed off" -between pods. - -**Important:** You must create an EBS volume using `aws ec2 create-volume` or the AWS API before you can use it. -{: .caution} - -There are some restrictions when using an awsElasticBlockStore volume: - -* the nodes on which pods are running must be AWS EC2 instances -* those instances need to be in the same region and availability-zone as the EBS volume -* EBS only supports a single EC2 instance mounting a volume - -#### Creating an EBS volume - -Before you can use an EBS volume with a pod, you need to create it. - -```shell -aws ec2 create-volume --availability-zone=eu-west-1a --size=10 --volume-type=gp2 -``` - -Make sure the zone matches the zone you brought up your cluster in. (And also check that the size and EBS volume -type are suitable for your use!) - -#### AWS EBS Example configuration - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: test-ebs -spec: - containers: - - image: gcr.io/google_containers/test-webserver - name: test-container - volumeMounts: - - mountPath: /test-ebs - name: test-volume - volumes: - - name: test-volume - # This AWS EBS volume must already exist. - awsElasticBlockStore: - volumeID: - fsType: ext4 -``` - -### nfs - -An `nfs` volume allows an existing NFS (Network File System) share to be -mounted into your pod. Unlike `emptyDir`, which is erased when a Pod is -removed, the contents of an `nfs` volume are preserved and the volume is merely -unmounted. This means that an NFS volume can be pre-populated with data, and -that data can be "handed off" between pods. NFS can be mounted by multiple -writers simultaneously. - -**Important:** You must have your own NFS server running with the share exported before you can use it. -{: .caution} - -See the [NFS example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/nfs) for more details. - ### iscsi An `iscsi` volume allows an existing iSCSI (SCSI over IP) volume to be mounted @@ -341,123 +432,71 @@ simultaneous writers allowed. See the [iSCSI example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/iscsi) for more details. -### fc (fibre channel) +### local -An `fc` volume allows an existing fibre channel volume to be mounted in a pod. -You can specify single or multiple target World Wide Names using the parameter -`targetWWNs` in your volume configuration. If multiple WWNs are specified, -targetWWNs expect that those WWNs are from multi-path connections. +This volume type is alpha in 1.7. -**Important:** You must configure FC SAN Zoning to allocate and mask those LUNs (volumes) to the target WWNs beforehand so that Kubernetes hosts can access them. -{: .caution} +A `local` volume represents a mounted local storage device such as a disk, +partition or directory. -See the [FC example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/fibre_channel) for more details. +Local volumes can only be used as a statically created PersistentVolume. -### flocker +Compared to HostPath volumes, local volumes can be used in a durable manner +without manually scheduling pods to nodes, as the system is aware of the volume's +node constraints. -[Flocker](https://clusterhq.com/flocker) is an open-source clustered container data volume manager. It provides management -and orchestration of data volumes backed by a variety of storage backends. +However, local volumes are still subject to the availability of the underlying +node and are not suitable for all applications. -A `flocker` volume allows a Flocker dataset to be mounted into a pod. If the -dataset does not already exist in Flocker, it needs to be first created with the Flocker -CLI or by using the Flocker API. If the dataset already exists it will be -reattached by Flocker to the node that the pod is scheduled. This means data -can be "handed off" between pods as required. +The following is an example PersistentVolume spec using a `local` volume: -**Important:** You must have your own Flocker installation running before you can use it. -{: .caution} - -See the [Flocker example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/flocker) for more details. - -### glusterfs - -A `glusterfs` volume allows a [Glusterfs](http://www.gluster.org) (an open -source networked filesystem) volume to be mounted into your pod. Unlike -`emptyDir`, which is erased when a Pod is removed, the contents of a -`glusterfs` volume are preserved and the volume is merely unmounted. This -means that a glusterfs volume can be pre-populated with data, and that data can -be "handed off" between pods. GlusterFS can be mounted by multiple writers -simultaneously. - -**Important:** You must have your own GlusterFS installation running before you can use it. -{: .caution} - -See the [GlusterFS example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/glusterfs) for more details. - -### rbd - -An `rbd` volume allows a [Rados Block -Device](http://ceph.com/docs/master/rbd/rbd/) volume to be mounted into your -pod. Unlike `emptyDir`, which is erased when a Pod is removed, the contents of -a `rbd` volume are preserved and the volume is merely unmounted. This -means that a RBD volume can be pre-populated with data, and that data can -be "handed off" between pods. - -**Important:** You must have your own Ceph installation running before you can use RBD. -{: .caution} - -A feature of RBD is that it can be mounted as read-only by multiple consumers -simultaneously. This means that you can pre-populate a volume with your dataset -and then serve it in parallel from as many pods as you need. Unfortunately, -RBD volumes can only be mounted by a single consumer in read-write mode - no -simultaneous writers allowed. - -See the [RBD example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/rbd) for more details. - -### cephfs - -A `cephfs` volume allows an existing CephFS volume to be -mounted into your pod. Unlike `emptyDir`, which is erased when a Pod is -removed, the contents of a `cephfs` volume are preserved and the volume is merely -unmounted. This means that a CephFS volume can be pre-populated with data, and -that data can be "handed off" between pods. CephFS can be mounted by multiple -writers simultaneously. - -**Important:** You must have your own Ceph server running with the share exported before you can use it. -{: .caution} - -See the [CephFS example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/cephfs/) for more details. - -### gitRepo - -A `gitRepo` volume is an example of what can be done as a volume plugin. It -mounts an empty directory and clones a git repository into it for your pod to -use. In the future, such volumes may be moved to an even more decoupled model, -rather than extending the Kubernetes API for every such use case. - -Here is an example for gitRepo volume: - -```yaml +``` yaml apiVersion: v1 -kind: Pod +kind: PersistentVolume metadata: - name: server + name: example-pv + annotations: + "volume.alpha.kubernetes.io/node-affinity": '{ + "requiredDuringSchedulingIgnoredDuringExecution": { + "nodeSelectorTerms": [ + { "matchExpressions": [ + { "key": "kubernetes.io/hostname", + "operator": "In", + "values": ["example-node"] + } + ]} + ]} + }' spec: - containers: - - image: nginx - name: nginx - volumeMounts: - - mountPath: /mypath - name: git-volume - volumes: - - name: git-volume - gitRepo: - repository: "git@somewhere:me/my-git-repository.git" - revision: "22f1d8406d464b0c0874075539c1f2e96c253775" + capacity: + storage: 100Gi + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Delete + storageClassName: local-storage + local: + path: /mnt/disks/ssd1 ``` -### secret +**Note:** The local PersistentVolume cleanup and deletion requires manual intervention without the external provisioner. +{: .note} -A `secret` volume is used to pass sensitive information, such as passwords, to -pods. You can store secrets in the Kubernetes API and mount them as files for -use by pods without coupling to Kubernetes directly. `secret` volumes are -backed by tmpfs (a RAM-backed filesystem) so they are never written to -non-volatile storage. +For details on the `local` volume type, see the [Local Persistent Storage +user guide](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume). -**Important:** You must create a secret in the Kubernetes API before you can use it. +### nfs + +An `nfs` volume allows an existing NFS (Network File System) share to be +mounted into your pod. Unlike `emptyDir`, which is erased when a Pod is +removed, the contents of an `nfs` volume are preserved and the volume is merely +unmounted. This means that an NFS volume can be pre-populated with data, and +that data can be "handed off" between pods. NFS can be mounted by multiple +writers simultaneously. + +**Important:** You must have your own NFS server running with the share exported before you can use it. {: .caution} -Secrets are described in more detail [here](/docs/user-guide/secrets). +See the [NFS example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/nfs) for more details. ### persistentVolumeClaim @@ -469,13 +508,6 @@ iSCSI volume) without knowing the details of the particular cloud environment. See the [PersistentVolumes example](/docs/concepts/storage/persistent-volumes/) for more details. -### downwardAPI - -A `downwardAPI` volume is used to make downward API data available to applications. -It mounts a directory and writes the requested data in plain text files. - -See the [`downwardAPI` volume example](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/) for more details. - ### projected A `projected` volume maps several existing volume sources into the same directory. @@ -564,27 +596,189 @@ Each projected volume source is listed in the spec under `sources`. The parameters are nearly the same with two exceptions: * For secrets, the `secretName` field has been changed to `name` to be consistent -with ConfigMap naming. + with ConfigMap naming. * The `defaultMode` can only be specified at the projected level and not for each -volume source. However, as illustrated above, you can explicitly set the `mode` -for each individual projection. + volume source. However, as illustrated above, you can explicitly set the `mode` + for each individual projection. -### AzureFileVolume +### portworxVolume -A `AzureFileVolume` is used to mount a Microsoft Azure File Volume (SMB 2.1 and 3.0) -into a Pod. +A `portworxVolume` is an elastic block storage layer that runs hyperconverged with +Kubernetes. Portworx fingerprints storage in a server, tiers based on capabilities, +and aggregates capacity across multiple servers. Portworx runs in-guest in virtual +machines or on bare metal Linux nodes. -More details can be found [here](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/azure_file/README.md). +A `portworxVolume` can be dynamically created through Kubernetes or it can also +be pre-provisioned and referenced inside a Kubernetes pod. +Here is an example pod referencing a pre-provisioned PortworxVolume: -### AzureDiskVolume +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: test-portworx-volume-pod +spec: + containers: + - image: gcr.io/google_containers/test-webserver + name: test-container + volumeMounts: + - mountPath: /mnt + name: pxvol + volumes: + - name: pxvol + # This Portworx volume must already exist. + portworxVolume: + volumeID: "pxvol" + fsType: "" +``` -A `AzureDiskVolume` is used to mount a Microsoft Azure [Data Disk](https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-linux-about-disks-vhds/) into a Pod. +**Important:** Make sure you have an existing PortworxVolume with name `pxvol` +before using it in the pod. +{: .caution} -More details can be found [here](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/azure_disk/README.md). +More details and examples can be found [here](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/portworx/README.md). + +### quobyte + +A `quobyte` volume allows an existing [Quobyte](http://www.quobyte.com) volume to +be mounted into your pod. + +**Important:** You must have your own Quobyte setup running with the volumes +created before you can use it. +{: .caution} + +See the [Quobyte example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/quobyte) for more details. + +### rbd + +An `rbd` volume allows a [Rados Block +Device](http://ceph.com/docs/master/rbd/rbd/) volume to be mounted into your +pod. Unlike `emptyDir`, which is erased when a Pod is removed, the contents of +a `rbd` volume are preserved and the volume is merely unmounted. This +means that a RBD volume can be pre-populated with data, and that data can +be "handed off" between pods. + +**Important:** You must have your own Ceph installation running before you can use RBD. +{: .caution} + +A feature of RBD is that it can be mounted as read-only by multiple consumers +simultaneously. This means that you can pre-populate a volume with your dataset +and then serve it in parallel from as many pods as you need. Unfortunately, +RBD volumes can only be mounted by a single consumer in read-write mode - no +simultaneous writers allowed. + +See the [RBD example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/rbd) for more details. + +### scaleIO + +ScaleIO is a software-based storage platform that can use existing hardware to +create clusters of scalable shared block networked storage. The `scaleIO` volume +plugin allows deployed pods to access existing ScaleIO +volumes (or it can dynamically provision new volumes for persistent volume claims, see +[ScaleIO Persistent Volumes](/docs/concepts/storage/persistent-volumes/#scaleio)). + +**Important:** You must have an existing ScaleIO cluster already setup and +running with the volumes created before you can use them. +{: .caution} + +The following is an example pod configuration with ScaleIO: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: pod-0 +spec: + containers: + - image: gcr.io/google_containers/test-webserver + name: pod-0 + volumeMounts: + - mountPath: /test-pd + name: vol-0 + volumes: + - name: vol-0 + scaleIO: + gateway: https://localhost:443/api + system: scaleio + protectionDomain: sd0 + storagePool: sp1 + volumeName: vol-0 + secretRef: + name: sio-secret + fsType: xfs +``` + +For further detail, please the see the [ScaleIO examples](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/scaleio). + +### secret + +A `secret` volume is used to pass sensitive information, such as passwords, to +pods. You can store secrets in the Kubernetes API and mount them as files for +use by pods without coupling to Kubernetes directly. `secret` volumes are +backed by tmpfs (a RAM-backed filesystem) so they are never written to +non-volatile storage. + +**Important:** You must create a secret in the Kubernetes API before you can use it. +{: .caution} + +Secrets are described in more detail [here](/docs/user-guide/secrets). + +### storageOS + +A `storageos` volume allows an existing [StorageOS](https://www.storageos.com) +volume to be mounted into your pod. + +StorageOS runs as a container within your Kubernetes environment, making local +or attached storage accessible from any node within the Kubernetes cluster. +Data can be replicated to protect against node failure. Thin provisioning and +compression can improve utilization and reduce cost. + +At its core, StorageOS provides block storage to containers, accessible via a file system. + +The StorageOS container requires 64-bit Linux and has no additional dependencies. +A free developer license is available. + +**Important:** You must run the StorageOS container on each node that wants to +access StorageOS volumes or that will contribute storage capacity to the pool. +For installation instructions, consult the +[StorageOS documentation](https://docs.storageos.com). +{: .caution} + +```yaml +apiVersion: v1 +kind: Pod +metadata: + labels: + name: redis + role: master + name: test-storageos-redis +spec: + containers: + - name: master + image: kubernetes/redis:v1 + env: + - name: MASTER + value: "true" + ports: + - containerPort: 6379 + volumeMounts: + - mountPath: /redis-master-data + name: redis-data + volumes: + - name: redis-data + storageos: + # The `redis-vol01` volume must already exist within StorageOS in the `default` namespace. + volumeName: redis-vol01 + fsType: ext4 +``` + +For more information including Dynamic Provisioning and Persistent Volume Claims, please see the +[StorageOS examples](https://github.com/kubernetes/kubernetes/tree/master/examples/volumes/storageos). ### vsphereVolume -**Prerequisite:** Kubernetes with vSphere Cloud Provider configured. For cloudprovider configuration please refer [vSphere getting started guide](/docs/getting-started-guides/vsphere/). +**Prerequisite:** Kubernetes with vSphere Cloud Provider configured. For cloudprovider +configuration please refer [vSphere getting started guide](/docs/getting-started-guides/vsphere/). {: .note} A `vsphereVolume` is used to mount a vSphere VMDK Volume into your Pod. The contents @@ -638,185 +832,10 @@ spec: volumePath: "[DatastoreName] volumes/myDisk" fsType: ext4 ``` + More examples can be found [here](https://github.com/kubernetes/examples/tree/master/staging/volumes/vsphere). -### Quobyte - -A `Quobyte` volume allows an existing [Quobyte](http://www.quobyte.com) volume to be mounted into your pod. - -**Important:** You must have your own Quobyte setup running with the volumes created before you can use it. -{: .caution} - -See the [Quobyte example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/quobyte) for more details. - -### PortworxVolume -A `PortworxVolume` is an elastic block storage layer that runs hyperconverged with Kubernetes. Portworx fingerprints storage in a -server, tiers based on capabilities, and aggregates capacity across multiple servers. Portworx runs in-guest in virtual machines or on bare metal -Linux nodes. - -A `PortworxVolume` can be dynamically created through Kubernetes or it can also be pre-provisioned and referenced inside a Kubernetes pod. -Here is an example pod referencing a pre-provisioned PortworxVolume: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: test-portworx-volume-pod -spec: - containers: - - image: gcr.io/google_containers/test-webserver - name: test-container - volumeMounts: - - mountPath: /mnt - name: pxvol - volumes: - - name: pxvol - # This Portworx volume must already exist. - portworxVolume: - volumeID: "pxvol" - fsType: "" -``` - -**Important:** Make sure you have an existing PortworxVolume with name `pxvol` before using it in the pod. -{: .caution} - -More details and examples can be found [here](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/portworx/README.md). - -### ScaleIO -ScaleIO is a software-based storage platform that can use existing hardware to create clusters of scalable -shared block networked storage. The ScaleIO volume plugin allows deployed pods to access existing ScaleIO -volumes (or it can dynamically provision new volumes for persistent volume claims, see -[ScaleIO Persistent Volumes](/docs/concepts/storage/persistent-volumes/#scaleio)). - -**Important:** You must have an existing ScaleIO cluster already setup and running with the volumes created before you can use them. -{: .caution} - -The following is an example pod configuration with ScaleIO: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: pod-0 -spec: - containers: - - image: gcr.io/google_containers/test-webserver - name: pod-0 - volumeMounts: - - mountPath: /test-pd - name: vol-0 - volumes: - - name: vol-0 - scaleIO: - gateway: https://localhost:443/api - system: scaleio - protectionDomain: sd0 - storagePool: sp1 - volumeName: vol-0 - secretRef: - name: sio-secret - fsType: xfs -``` - -For further detail, please the see the [ScaleIO examples](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/scaleio). - -### StorageOS -A `storageos` volume allows an existing [StorageOS](https://www.storageos.com) volume to be mounted into your pod. - -StorageOS runs as a container within your Kubernetes environment, making local or attached storage accessible from any node within the Kubernetes cluster. Data can be replicated to protect against node failure. Thin provisioning and compression can improve utilization and reduce cost. - -At its core, StorageOS provides block storage to containers, accessible via a file system. - -The StorageOS container requires 64-bit Linux and has no additional dependencies. A free developer licence is available. - -**Important:** You must run the StorageOS container on each node that wants to access StorageOS volumes or that will contribute storage capacity to the pool. For installation instructions, consult the [StorageOS documentation](https://docs.storageos.com). -{: .caution} - -```yaml -apiVersion: v1 -kind: Pod -metadata: - labels: - name: redis - role: master - name: test-storageos-redis -spec: - containers: - - name: master - image: kubernetes/redis:v1 - env: - - name: MASTER - value: "true" - ports: - - containerPort: 6379 - volumeMounts: - - mountPath: /redis-master-data - name: redis-data - volumes: - - name: redis-data - storageos: - # The `redis-vol01` volume must already exist within StorageOS in the `default` namespace. - volumeName: redis-vol01 - fsType: ext4 -``` - -For more information including Dynamic Provisioning and Persistent Volume Claims, please see the -[StorageOS examples](https://github.com/kubernetes/kubernetes/tree/master/examples/volumes/storageos). - - -### local - -This volume type is alpha in 1.7. - -A `local` volume represents a mounted local storage device such as a disk, -partition or directory. - -Local volumes can only be used as a statically created PersistentVolume. - -Compared to HostPath volumes, local volumes can be used in a durable manner -without manually scheduling pods to nodes, as the system is aware of the volume's -node constraints. - -However, local volumes are still subject to the availability of the underlying -node and are not suitable for all applications. - -The following is an example PersistentVolume spec using a `local` volume: - -``` yaml -apiVersion: v1 -kind: PersistentVolume -metadata: - name: example-pv - annotations: - "volume.alpha.kubernetes.io/node-affinity": '{ - "requiredDuringSchedulingIgnoredDuringExecution": { - "nodeSelectorTerms": [ - { "matchExpressions": [ - { "key": "kubernetes.io/hostname", - "operator": "In", - "values": ["example-node"] - } - ]} - ]} - }' -spec: - capacity: - storage: 100Gi - accessModes: - - ReadWriteOnce - persistentVolumeReclaimPolicy: Delete - storageClassName: local-storage - local: - path: /mnt/disks/ssd1 -``` - -**Note:** The local PersistentVolume cleanup and deletion requires manual intervention without the external provisioner. -{: .note} - -For details on the `local` volume type, see the [Local Persistent Storage -user guide](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume). - ## Using subPath Sometimes, it is useful to share one volume for multiple uses in a single pod. The `volumeMounts.subPath`