From 7865afe45928f1c528bbb8ddf50e4d6bacf1d50f Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Tue, 24 Oct 2017 11:29:58 +0800 Subject: [PATCH 1/4] 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 da6e3216696124ac92c96ff50d5290307bddb86d Mon Sep 17 00:00:00 2001 From: XsWack Date: Thu, 16 Nov 2017 01:43:17 +0800 Subject: [PATCH 2/4] 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 3/4] 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 4/4] 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.