diff --git a/config.toml b/config.toml index bf24f39d28..227afab894 100644 --- a/config.toml +++ b/config.toml @@ -157,7 +157,7 @@ github_repo = "https://github.com/kubernetes/website" # param for displaying an announcement block on every page. # See /i18n/en.toml for message text and title. announcement = true -announcement_bg = "#000000" #choose a dark color – text is white +announcement_bg = "#3f0374" # choose a dark color – text is white #Searching k8s_search = true diff --git a/content/en/docs/concepts/storage/volume-snapshots.md b/content/en/docs/concepts/storage/volume-snapshots.md index 51da1b05ae..a93ea27e05 100644 --- a/content/en/docs/concepts/storage/volume-snapshots.md +++ b/content/en/docs/concepts/storage/volume-snapshots.md @@ -31,6 +31,8 @@ A `VolumeSnapshot` is a request for snapshot of a volume by a user. It is simila `VolumeSnapshotClass` allows you to specify different attributes belonging to a `VolumeSnapshot`. These attributes may differ among snapshots taken from the same volume on the storage system and therefore cannot be expressed by using the same `StorageClass` of a `PersistentVolumeClaim`. +Volume snapshots provide Kubernetes users with a standardized way to copy a volume's contents at a particular point in time without creating an entirely new volume. This functionality enables, for example, database administrators to backup databases before performing edit or delete modifications. + Users need to be aware of the following when using this feature: * API Objects `VolumeSnapshot`, `VolumeSnapshotContent`, and `VolumeSnapshotClass` are {{< glossary_tooltip term_id="CustomResourceDefinition" text="CRDs" >}}, not part of the core API. @@ -152,6 +154,4 @@ You can provision a new volume, pre-populated with data from a snapshot, by usin the *dataSource* field in the `PersistentVolumeClaim` object. For more details, see -[Volume Snapshot and Restore Volume from Snapshot](/docs/concepts/storage/persistent-volumes/#volume-snapshot-and-restore-volume-from-snapshot-support). - - +[Volume Snapshot and Restore Volume from Snapshot](/docs/concepts/storage/persistent-volumes/#volume-snapshot-and-restore-volume-from-snapshot-support). \ No newline at end of file diff --git a/content/en/docs/concepts/storage/volumes.md b/content/en/docs/concepts/storage/volumes.md index e4f38e7d2b..7645b7e5fa 100644 --- a/content/en/docs/concepts/storage/volumes.md +++ b/content/en/docs/concepts/storage/volumes.md @@ -11,119 +11,80 @@ weight: 10 -On-disk files in a Container are ephemeral, which presents some problems for -non-trivial applications when running in Containers. First, when a Container -crashes, kubelet will restart it, but the files will be lost - the -Container starts with a clean state. Second, when running Containers together -in a `Pod` it is often necessary to share files between those Containers. The -Kubernetes `Volume` abstraction solves both of these problems. - +On-disk files in a container are ephemeral, which presents some problems for +non-trivial applications when running in containers. One problem +is the loss of files when a container crashes. The kubelet restarts the container +but with a clean state. A second problem occurs when sharing files +between containers running together in a `Pod`. +The Kubernetes {{< glossary_tooltip text="volume" term_id="volume" >}} abstraction +solves both of these problems. Familiarity with [Pods](/docs/concepts/workloads/pods/) is suggested. ## Background -Docker also has a concept of +Docker has a concept of [volumes](https://docs.docker.com/storage/), though it is -somewhat looser and less managed. In Docker, a volume is simply a directory on -disk or in another Container. Lifetimes are not managed and until very -recently there were only local-disk-backed volumes. Docker now provides volume -drivers, but the functionality is very limited for now (e.g. as of Docker 1.7 -only one volume driver is allowed per Container and there is no way to pass -parameters to volumes). +somewhat looser and less managed. A Docker volume is a directory on +disk or in another container. Docker provides volume +drivers, but the functionality is somewhat limited. -A Kubernetes volume, on the other hand, has an explicit lifetime - the same as -the Pod that encloses it. Consequently, a volume outlives any Containers that run -within the Pod, and data is preserved across Container restarts. Of course, when a -Pod ceases to exist, the volume will cease to exist, too. Perhaps more -importantly than this, Kubernetes supports many types of volumes, and a Pod can -use any number of them simultaneously. +Kubernetes supports many types of volumes. A {{< glossary_tooltip term_id="pod" text="Pod" >}} +can use any number of volume types simultaneously. +Ephemeral volume types have a lifetime of a pod, but persistent volumes exist beyond +the lifetime of a pod. Consequently, a volume outlives any containers +that run within the pod, and data is preserved across container restarts. When a +pod ceases to exist, the volume is destroyed. At its core, a volume is just a directory, possibly with some data in it, which -is accessible to the Containers in a Pod. How that directory comes to be, the +is accessible to the containers in a pod. How that directory comes to be, the medium that backs it, and the contents of it are determined by the particular volume type used. -To use a volume, a Pod specifies what volumes to provide for the Pod (the -`.spec.volumes` -field) and where to mount those into Containers (the -`.spec.containers[*].volumeMounts` -field). - +To use a volume, specify the volumes to provide for the Pod in `.spec.volumes` +and declare where to mount those volumes into containers in `.spec.containers[*].volumeMounts`. A process in a container sees a filesystem view composed from their Docker -image and volumes. The [Docker image](https://docs.docker.com/userguide/dockerimages/) is at the root of the -filesystem hierarchy, and any volumes are mounted at the specified paths within -the image. Volumes can not mount onto other volumes or have hard links to -other volumes. Each Container in the Pod must independently specify where to +image and volumes. The [Docker image](https://docs.docker.com/userguide/dockerimages/) +is at the root of the filesystem hierarchy. Volumes mount at the specified paths within +the image. Volumes can not mount onto other volumes or have hard links to +other volumes. Each Container in the Pod's configuration must independently specify where to mount each volume. -## Types of Volumes +## Types of Volumes {#volume-types} -Kubernetes supports several types of Volumes: - - * [awsElasticBlockStore](#awselasticblockstore) - * [azureDisk](#azuredisk) - * [azureFile](#azurefile) - * [cephfs](#cephfs) - * [cinder](#cinder) - * [configMap](#configmap) - * [csi](#csi) - * [downwardAPI](#downwardapi) - * [emptyDir](#emptydir) - * [fc (fibre channel)](#fc) - * [flexVolume](#flexVolume) - * [flocker](#flocker) - * [gcePersistentDisk](#gcepersistentdisk) - * [gitRepo (deprecated)](#gitrepo) - * [glusterfs](#glusterfs) - * [hostPath](#hostpath) - * [iscsi](#iscsi) - * [local](#local) - * [nfs](#nfs) - * [persistentVolumeClaim](#persistentvolumeclaim) - * [projected](#projected) - * [portworxVolume](#portworxvolume) - * [quobyte](#quobyte) - * [rbd](#rbd) - * [scaleIO](#scaleio) - * [secret](#secret) - * [storageos](#storageos) - * [vsphereVolume](#vspherevolume) - -We welcome additional contributions. +Kubernetes supports several types of volumes. ### awsElasticBlockStore {#awselasticblockstore} -An `awsElasticBlockStore` volume mounts an Amazon Web Services (AWS) [EBS -Volume](https://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. +An `awsElasticBlockStore` volume mounts an Amazon Web Services (AWS) +[EBS volume](https://aws.amazon.com/ebs/) into your pod. Unlike +`emptyDir`, which is erased when a pod is removed, the contents of an EBS +volume are persisted and the volume is unmounted. This means that an +EBS volume can be pre-populated with data, and that data can be shared between pods. -{{< caution >}} -You must create an EBS volume using `aws ec2 create-volume` or the AWS API before you can use it. -{{< /caution >}} +{{< note >}} +You must create an EBS volume by using `aws ec2 create-volume` or the AWS API before you can use it. +{{< /note >}} 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 +* 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 +#### Creating an AWS EBS volume -Before you can use an EBS volume with a Pod, you need to create it. +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!) +Make sure the zone matches the zone you brought up your cluster in. Check that the size and EBS volume +type are suitable for your use. -#### AWS EBS Example configuration +#### AWS EBS configuration example ```yaml apiVersion: v1 @@ -141,37 +102,39 @@ spec: - name: test-volume # This AWS EBS volume must already exist. awsElasticBlockStore: - volumeID: + volumeID: "" fsType: ext4 ``` -#### CSI Migration +#### AWS EBS CSI migration {{< feature-state for_k8s_version="v1.17" state="beta" >}} -The CSI Migration feature for awsElasticBlockStore, when enabled, shims all plugin operations -from the existing in-tree plugin to the `ebs.csi.aws.com` Container -Storage Interface (CSI) Driver. In order to use this feature, the [AWS EBS CSI -Driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) +The `CSIMigration` feature for `awsElasticBlockStore`, when enabled, redirects +all plugin operations from the existing in-tree plugin to the `ebs.csi.aws.com` Container +Storage Interface (CSI) driver. In order to use this feature, the [AWS EBS CSI +driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) must be installed on the cluster and the `CSIMigration` and `CSIMigrationAWS` -Beta features must be enabled. +beta features must be enabled. + +#### AWS EBS CSI migration complete -#### CSI Migration Complete {{< feature-state for_k8s_version="v1.17" state="alpha" >}} -To turn off the awsElasticBlockStore storage plugin from being loaded by controller manager and kubelet, you need to set this feature flag to true. This requires `ebs.csi.aws.com` Container Storage Interface (CSI) driver being installed on all worker nodes. +To disable the `awsElasticBlockStore` storage plugin from being loaded by the controller manager +and the kubelet, set the `CSIMigrationAWSComplete` flag to `true`. This feature requires the `ebs.csi.aws.com` Container Storage Interface (CSI) driver installed on all worker nodes. ### azureDisk {#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. +The `azureDisk` volume type mounts a Microsoft Azure [Data Disk](https://docs.microsoft.com/en-us/azure/aks/csi-storage-drivers) into a pod. -More details can be found [here](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/azure_disk/README.md). +For more details, see the [`azureDisk` volume plugin](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/azure_disk/README.md). -#### CSI Migration +#### azureDisk CSI migration {{< feature-state for_k8s_version="v1.19" state="beta" >}} -The CSI Migration feature for azureDisk, when enabled, shims all plugin operations +The `CSIMigration` feature for `azureDisk`, when enabled, redirects all plugin operations from the existing in-tree plugin to the `disk.csi.azure.com` Container Storage Interface (CSI) Driver. In order to use this feature, the [Azure Disk CSI Driver](https://github.com/kubernetes-sigs/azuredisk-csi-driver) @@ -180,46 +143,46 @@ features must be enabled. ### azureFile {#azurefile} -A `azureFile` is used to mount a Microsoft Azure File Volume (SMB 2.1 and 3.0) -into a Pod. +The `azureFile` volume type mounts 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/{{< param "githubbranch" >}}/staging/volumes/azure_file/README.md). +For more details, see the [`azureFile` volume plugin](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/azure_file/README.md). -#### CSI Migration +#### azureFile CSI migration {{< feature-state for_k8s_version="v1.15" state="alpha" >}} -The CSI Migration feature for azureFile, when enabled, shims all plugin operations +The `CSIMigration` feature for `azureFile`, when enabled, redirects all plugin operations from the existing in-tree plugin to the `file.csi.azure.com` Container Storage Interface (CSI) Driver. In order to use this feature, the [Azure File CSI Driver](https://github.com/kubernetes-sigs/azurefile-csi-driver) must be installed on the cluster and the `CSIMigration` and `CSIMigrationAzureFile` -Alpha features must be enabled. +alpha features must be enabled. -### cephfs {#cephfs} +### cephfs A `cephfs` volume allows an existing CephFS volume to be -mounted into your Pod. Unlike `emptyDir`, which is erased when a Pod is +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 +unmounted. This means that a `cephfs` volume can be pre-populated with data, and +that data can be shared between pods. The `cephfs` volume can be mounted by multiple writers simultaneously. -{{< caution >}} +{{< note >}} You must have your own Ceph server running with the share exported before you can use it. -{{< /caution >}} +{{< /note >}} See the [CephFS example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/volumes/cephfs/) for more details. -### cinder {#cinder} +### cinder {{< note >}} -Prerequisite: Kubernetes with OpenStack Cloud Provider configured. +Kubernetes must be configured with the OpenStack cloud provider. {{< /note >}} -`cinder` is used to mount OpenStack Cinder Volume into your Pod. +The `cinder` volume type is used to mount the OpenStack Cinder volume into your pod. -#### Cinder Volume Example configuration +#### Cinder volume configuration example ```yaml apiVersion: v1 @@ -237,33 +200,32 @@ spec: - name: test-volume # This OpenStack volume must already exist. cinder: - volumeID: + volumeID: "" fsType: ext4 ``` -#### CSI Migration +#### OpenStack CSI migration {{< feature-state for_k8s_version="v1.18" state="beta" >}} -The CSI Migration feature for Cinder, when enabled, shims all plugin operations +The `CSIMigration` feature for Cinder, when enabled, redirects all plugin operations from the existing in-tree plugin to the `cinder.csi.openstack.org` Container Storage Interface (CSI) Driver. In order to use this feature, the [Openstack Cinder CSI Driver](https://github.com/kubernetes/cloud-provider-openstack/blob/master/docs/using-cinder-csi-plugin.md) must be installed on the cluster and the `CSIMigration` and `CSIMigrationOpenStack` -Beta features must be enabled. +beta features must be enabled. -### configMap {#configmap} +### configMap -The [`configMap`](/docs/tasks/configure-pod-container/configure-pod-configmap/) resource -provides a way to inject configuration data into Pods. -The data stored in a `ConfigMap` object can be referenced in a volume of type -`configMap` and then consumed by containerized applications running in a Pod. +A [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) +provides a way to inject configuration data into pods. +The data stored in a ConfigMap can be referenced in a volume of type +`configMap` and then consumed by containerized applications running in a pod. -When referencing a `configMap` object, you can simply provide its name in the -volume to reference it. You can also customize the path to use for a specific -entry in the ConfigMap. -For example, to mount the `log-config` ConfigMap onto a Pod called `configmap-pod`, -you might use the YAML below: +When referencing a ConfigMap, you provide the name of the ConfigMap in the +volume. You can customize the path to use for a specific +entry in the ConfigMap. The following configuration shows how to mount +the `log-config` ConfigMap onto a Pod called `configmap-pod`: ```yaml apiVersion: v1 @@ -287,65 +249,61 @@ spec: ``` The `log-config` ConfigMap is mounted as a volume, and all contents stored in -its `log_level` entry are mounted into the Pod at path "`/etc/config/log_level`". +its `log_level` entry are mounted into the Pod at path `/etc/config/log_level`. Note that this path is derived from the volume's `mountPath` and the `path` keyed with `log_level`. -{{< caution >}} -You must create a [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) before you can use it. -{{< /caution >}} - {{< note >}} -A Container using a ConfigMap as a [subPath](#using-subpath) volume mount will not -receive ConfigMap updates. -{{< /note >}} +* You must create a [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) + before you can use it. -{{< note >}} -Text data is exposed as files using the UTF-8 character encoding. To use some other character encoding, use binaryData. -{{< /note >}} +* A container using a ConfigMap as a [`subPath`](#using-subpath) volume mount will not + receive ConfigMap updates. +* Text data is exposed as files using the UTF-8 character encoding. For other character encodings, use `binaryData`. +{{< /note >}} ### downwardAPI {#downwardapi} -A `downwardAPI` volume is used to make downward API data available to applications. +A `downwardAPI` volume makes downward API data available to applications. It mounts a directory and writes the requested data in plain text files. {{< note >}} -A Container using Downward API as a [subPath](#using-subpath) volume mount will not -receive Downward API updates. +A container using the downward API as a [`subPath`](#using-subpath) volume mount will not +receive downward API updates. {{< /note >}} -See the [`downwardAPI` volume example](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/) for more details. +See the [downward API example](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/) for more details. ### emptyDir {#emptydir} -An `emptyDir` volume is first created when a Pod is assigned to a Node, and -exists as long as that Pod is running on that node. As the name says, it is -initially empty. Containers in the Pod can all read and write the same +An `emptyDir` volume is first created when a Pod is assigned to a node, and +exists as long as that Pod is running on that node. As the name says, the +`emptyDir` volume is initially empty. All containers in the Pod can read and write the same files in the `emptyDir` volume, though that volume can be mounted at the same -or different paths in each Container. When a Pod is removed from a node for -any reason, the data in the `emptyDir` is deleted forever. +or different paths in each container. When a Pod is removed from a node for +any reason, the data in the `emptyDir` is deleted permanently. {{< note >}} -A Container crashing does *NOT* remove a Pod from a node, so the data in an `emptyDir` volume is safe across Container crashes. +A container crashing does *not* remove a Pod from a node. The data in an `emptyDir` volume +is safe across container crashes. {{< /note >}} Some uses for an `emptyDir` are: * scratch space, such as for a disk-based merge sort * checkpointing a long computation for recovery from crashes -* holding files that a content-manager Container fetches while a webserver - Container serves the data +* holding files that a content-manager container fetches while a webserver + container serves the data -By default, `emptyDir` volumes are stored on whatever medium is backing the -node - that might be disk or SSD or network storage, depending on your -environment. However, you can set the `emptyDir.medium` field to `"Memory"` -to tell Kubernetes to mount a tmpfs (RAM-backed filesystem) for you instead. +Depending on your environment, `emptyDir` volumes are stored on whatever medium that backs the +node such as disk or SSD, or network storage. However, if you set the `emptyDir.medium` field +to `"Memory"`, Kubernetes mounts a tmpfs (RAM-backed filesystem) for you instead. While tmpfs is very fast, be aware that unlike disks, tmpfs is cleared on -node reboot and any files you write will count against your Container's +node reboot and any files you write count against your container's memory limit. -#### Example Pod +#### emptyDir configuration example ```yaml apiVersion: v1 @@ -366,69 +324,72 @@ spec: ### fc (fibre channel) {#fc} -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, +An `fc` volume type allows an existing fibre channel block storage volume +to mount in a Pod. You can specify single or multiple target world wide names (WWNs) +using the parameter `targetWWNs` in your Volume configuration. If multiple WWNs are specified, targetWWNs expect that those WWNs are from multi-path connections. -{{< caution >}} -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 >}} +{{< note >}} +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. +{{< /note >}} -See the [FC example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/fibre_channel) for more details. +See the [fibre channel example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/fibre_channel) for more details. -### flocker {#flocker} +### flocker (deprecated) {#flocker} -[Flocker](https://github.com/ClusterHQ/flocker) is an open-source clustered Container data volume manager. It provides management +[Flocker](https://github.com/ClusterHQ/flocker) is an open-source, clustered +container data volume manager. Flocker 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. +reattached by Flocker to the node that the pod is scheduled. This means data +can be shared between pods as required. -{{< caution >}} +{{< note >}} You must have your own Flocker installation running before you can use it. -{{< /caution >}} +{{< /note >}} See the [Flocker example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/flocker) for more details. -### gcePersistentDisk {#gcepersistentdisk} +### gcePersistentDisk A `gcePersistentDisk` volume mounts a Google Compute Engine (GCE) -[Persistent Disk](https://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. +[persistent disk](https://cloud.google.com/compute/docs/disks) (PD) 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 shared between pods. -{{< caution >}} +{{< note >}} You must create a PD using `gcloud` or the GCE API or UI before you can use it. -{{< /caution >}} +{{< /note >}} 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 +* those VMs need to be in the same GCE project and zone as the persistent disk -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. +One feature of GCE persistent disk is concurrent read-only access to a persistent disk. +A `gcePersistentDisk` volume permits multiple consumers to simultaneously +mount a persistent disk as read-only. 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. Simultaneous +writers are not allowed. -Using a PD on a Pod controlled by a ReplicationController will fail unless +Using a GCE persistent disk with a Pod controlled by a ReplicaSet will fail unless the PD is read-only or the replica count is 0 or 1. -#### Creating a PD +#### Creating a GCE persistent disk {#gce-create-persistent-disk} -Before you can use a GCE PD with a Pod, you need to create it. +Before you can use a GCE persistent disk with a Pod, you need to create it. ```shell gcloud compute disks create --size=500GB --zone=us-central1-a my-data-disk ``` -#### Example Pod +#### GCE persistent disk configuration example ```yaml apiVersion: v1 @@ -450,18 +411,26 @@ spec: fsType: ext4 ``` -#### Regional Persistent Disks -The [Regional Persistent Disks](https://cloud.google.com/compute/docs/disks/#repds) feature allows the creation of Persistent Disks that are available in two zones within the same region. In order to use this feature, the volume must be provisioned as a PersistentVolume; referencing the volume directly from a pod is not supported. +#### Regional persistent disks + +The [Regional persistent disks](https://cloud.google.com/compute/docs/disks/#repds) +feature allows the creation of persistent disks that are available in two zones +within the same region. In order to use this feature, the volume must be provisioned +as a PersistentVolume; referencing the volume directly from a pod is not supported. #### Manually provisioning a Regional PD PersistentVolume -Dynamic provisioning is possible using a [StorageClass for GCE PD](/docs/concepts/storage/storage-classes/#gce). -Before creating a PersistentVolume, you must create the PD: + +Dynamic provisioning is possible using a +[StorageClass for GCE PD](/docs/concepts/storage/storage-classes/#gce). +Before creating a PersistentVolume, you must create the persistent disk: + ```shell gcloud compute disks create --size=500GB my-data-disk - --region us-central1 - --replica-zones us-central1-a,us-central1-b + --region us-central1 + --replica-zones us-central1-a,us-central1-b ``` -Example PersistentVolume spec: + +#### Regional persistent disk configuration example ```yaml apiVersion: v1 @@ -487,29 +456,28 @@ spec: - us-central1-b ``` -#### CSI Migration +#### GCE CSI migration {{< feature-state for_k8s_version="v1.17" state="beta" >}} -The CSI Migration feature for GCE PD, when enabled, shims all plugin operations +The `CSIMigration` feature for GCE PD, when enabled, redirects all plugin operations from the existing in-tree plugin to the `pd.csi.storage.gke.io` Container Storage Interface (CSI) Driver. In order to use this feature, the [GCE PD CSI Driver](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver) must be installed on the cluster and the `CSIMigration` and `CSIMigrationGCE` -Beta features must be enabled. +beta features must be enabled. ### gitRepo (deprecated) {#gitrepo} {{< warning >}} -The gitRepo volume type is deprecated. To provision a container with a git repo, mount an [EmptyDir](#emptydir) into an InitContainer that clones the repo using git, then mount the [EmptyDir](#emptydir) into the Pod's container. +The `gitRepo` volume type is deprecated. To provision a container with a git repo, mount an [EmptyDir](#emptydir) into an InitContainer that clones the repo using git, then mount the [EmptyDir](#emptydir) into the Pod's container. {{< /warning >}} -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. +A `gitRepo` volume is an example of a volume plugin. This plugin +mounts an empty directory and clones a git repository into this directory +for your Pod to use. -Here is an example of gitRepo volume: +Here is an example of a `gitRepo` volume: ```yaml apiVersion: v1 @@ -530,19 +498,19 @@ spec: revision: "22f1d8406d464b0c0874075539c1f2e96c253775" ``` -### glusterfs {#glusterfs} +### glusterfs A `glusterfs` volume allows a [Glusterfs](https://www.gluster.org) (an open -source networked filesystem) volume to be mounted into your Pod. Unlike +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 +`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 +be shared between pods. GlusterFS can be mounted by multiple writers simultaneously. -{{< caution >}} +{{< note >}} You must have your own GlusterFS installation running before you can use it. -{{< /caution >}} +{{< /note >}} See the [GlusterFS example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/volumes/glusterfs) for more details. @@ -554,17 +522,16 @@ powerful escape hatch for some applications. For example, some uses for a `hostPath` are: -* running a Container that needs access to Docker internals; use a `hostPath` +* running a container that needs access to Docker internals; use a `hostPath` of `/var/lib/docker` -* running cAdvisor in a Container; use a `hostPath` of `/sys` +* running cAdvisor in a container; use a `hostPath` of `/sys` * allowing a Pod to specify whether a given `hostPath` should exist prior to the Pod running, whether it should be created, and what it should exist as -In addition to the required `path` property, user can optionally specify a `type` for a `hostPath` volume. +In addition to the required `path` property, you can optionally specify a `type` for a `hostPath` volume. The supported values for field `type` are: - | Value | Behavior | |:------|:---------| | | Empty string (default) is for backward compatibility, which means that no checks will be performed before mounting the hostPath volume. | @@ -578,16 +545,14 @@ The supported values for field `type` are: Watch out when using this type of volume, because: -* Pods with identical configuration (such as created from a podTemplate) may +* Pods with identical configuration (such as created from a PodTemplate) may behave differently on different nodes due to different files on the nodes -* when Kubernetes adds resource-aware scheduling, as is planned, it will not be - able to account for resources used by a `hostPath` -* the files or directories created on the underlying hosts are only writable by root. You +* The files or directories created on the underlying hosts are only writable by root. You either need to run your process as root in a [privileged Container](/docs/tasks/configure-pod-container/security-context/) or modify the file permissions on the host to be able to write to a `hostPath` volume -#### Example Pod +#### hostPath configuration example ```yaml apiVersion: v1 @@ -611,10 +576,13 @@ spec: ``` {{< caution >}} -It should be noted that the `FileOrCreate` mode does not create the parent directory of the file. If the parent directory of the mounted file does not exist, the pod fails to start. To ensure that this mode works, you can try to mount directories and files separately, as shown below. +The `FileOrCreate` mode does not create the parent directory of the file. If the parent directory +of the mounted file does not exist, the pod fails to start. To ensure that this mode works, +you can try to mount directories and files separately, as shown in the +[`FileOrCreate`configuration](#hostpath-fileorcreate-example). {{< /caution >}} -#### Example Pod FileOrCreate +#### hostPath FileOrCreate configuration example {#hostpath-fileorcreate-example} ```yaml apiVersion: v1 @@ -642,48 +610,46 @@ spec: type: FileOrCreate ``` -### iscsi {#iscsi} +### iscsi An `iscsi` volume allows an existing iSCSI (SCSI over IP) volume to be mounted -into your Pod. Unlike `emptyDir`, which is erased when a Pod is removed, the +into your Pod. Unlike `emptyDir`, which is erased when a Pod is removed, the contents of an `iscsi` volume are preserved and the volume is merely -unmounted. This means that an iscsi volume can be pre-populated with data, and -that data can be "handed off" between Pods. +unmounted. This means that an iscsi volume can be pre-populated with data, and +that data can be shared between pods. -{{< caution >}} +{{< note >}} You must have your own iSCSI server running with the volume created before you can use it. -{{< /caution >}} +{{< /note >}} A feature of iSCSI 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, -iSCSI volumes can only be mounted by a single consumer in read-write mode - no -simultaneous writers allowed. +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, +iSCSI volumes can only be mounted by a single consumer in read-write mode. +Simultaneous writers are not allowed. See the [iSCSI example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/volumes/iscsi) for more details. -### local {#local} - -{{< feature-state for_k8s_version="v1.14" state="stable" >}} +### local 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. Dynamic -provisioning is not supported yet. +provisioning is not supported. -Compared to `hostPath` volumes, local volumes can be used in a durable and -portable manner without manually scheduling Pods to nodes, as the system is aware +Compared to `hostPath` volumes, `local` volumes are used in a durable and +portable manner without manually scheduling pods to nodes. The system is aware of the volume's node constraints by looking at the node affinity on the PersistentVolume. -However, local volumes are still subject to the availability of the underlying +However, `local` volumes are subject to the availability of the underlying node and are not suitable for all applications. If a node becomes unhealthy, -then the local volume will also become inaccessible, and a Pod using it will not -be able to run. Applications using local volumes must be able to tolerate this +then the `local` volume becomes inaccessible by the pod. The pod using this volume +is unable to run. Applications using `local` volumes must be able to tolerate this reduced availability, as well as potential data loss, depending on the durability characteristics of the underlying disk. -The following is an example of PersistentVolume spec using a `local` volume and +The following example shows a PersistentVolume using a `local` volume and `nodeAffinity`: ```yaml @@ -711,19 +677,19 @@ spec: - example-node ``` -PersistentVolume `nodeAffinity` is required when using local volumes. It enables -the Kubernetes scheduler to correctly schedule Pods using local volumes to the -correct node. +You must set a PersistentVolume `nodeAffinity` when using `local` volumes. +The Kubernetes scheduler uses the PersistentVolume `nodeAffinity` to schedule +these Pods to the correct node. PersistentVolume `volumeMode` can be set to "Block" (instead of the default value "Filesystem") to expose the local volume as a raw block device. When using local volumes, it is recommended to create a StorageClass with -`volumeBindingMode` set to `WaitForFirstConsumer`. See the -[example](/docs/concepts/storage/storage-classes/#local). Delaying volume binding ensures -that the PersistentVolumeClaim binding decision will also be evaluated with any -other node constraints the Pod may have, such as node resource requirements, node -selectors, Pod affinity, and Pod anti-affinity. +`volumeBindingMode` set to `WaitForFirstConsumer`. For more details, see the +local [StorageClass](/docs/concepts/storage/storage-classes/#local) example. +Delaying volume binding ensures that the PersistentVolumeClaim binding decision +will also be evaluated with any other node constraints the Pod may have, +such as node resource requirements, node selectors, Pod affinity, and Pod anti-affinity. An external static provisioner can be run separately for improved management of the local volume lifecycle. Note that this provisioner does not support dynamic @@ -737,18 +703,18 @@ user if the external static provisioner is not used to manage the volume lifecycle. {{< /note >}} -### nfs {#nfs} +### 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 +mounted into a 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 +unmounted. This means that an NFS volume can be pre-populated with data, and +that data can be shared between pods. NFS can be mounted by multiple writers simultaneously. -{{< caution >}} +{{< note >}} You must have your own NFS server running with the share exported before you can use it. -{{< /caution >}} +{{< /note >}} See the [NFS example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/nfs) for more details. @@ -759,30 +725,62 @@ A `persistentVolumeClaim` volume is used to mount a are a way for users to "claim" durable storage (such as a GCE PersistentDisk or an iSCSI volume) without knowing the details of the particular cloud environment. -See the [PersistentVolumes example](/docs/concepts/storage/persistent-volumes/) for more +See the information about [PersistentVolumes](/docs/concepts/storage/persistent-volumes/) for more details. -### projected {#projected} +### portworxVolume {#portworxvolume} + +A `portworxVolume` is an elastic block storage layer that runs hyperconverged with +Kubernetes. [Portworx](https://portworx.com/use-case/kubernetes-storage/) 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 Pod. +Here is an example Pod referencing a pre-provisioned Portworx volume: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: test-portworx-volume-pod +spec: + containers: + - image: k8s.gcr.io/test-webserver + name: test-container + volumeMounts: + - mountPath: /mnt + name: pxvol + volumes: + - name: pxvol + # This Portworx volume must already exist. + portworxVolume: + volumeID: "pxvol" + fsType: "" +``` + +{{< note >}} +Make sure you have an existing PortworxVolume with name `pxvol` +before using it in the Pod. +{{< /note >}} + +For more details, see the [Portworx volume](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/portworx/README.md) examples. + +### projected A `projected` volume maps several existing volume sources into the same directory. Currently, the following types of volume sources can be projected: -- [`secret`](#secret) -- [`downwardAPI`](#downwardapi) -- [`configMap`](#configmap) -- `serviceAccountToken` +* [`secret`](#secret) +* [`downwardAPI`](#downwardapi) +* [`configMap`](#configmap) +* `serviceAccountToken` All sources are required to be in the same namespace as the Pod. For more details, see the [all-in-one volume design document](https://github.com/kubernetes/community/blob/{{< param "githubbranch" >}}/contributors/design-proposals/node/all-in-one-volume.md). -The projection of service account tokens is a feature introduced in Kubernetes -1.11 and promoted to Beta in 1.12. -To enable this feature on 1.11, you need to explicitly set the `TokenRequestProjection` -[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to -True. - -#### Example Pod with a secret, a downward API, and a configmap. +#### Example configuration with a secret, a downwardAPI, and a configMap {#example-configuration-secret-downwardapi-configmap} ```yaml apiVersion: v1 @@ -822,7 +820,7 @@ spec: path: my-group/my-config ``` -#### Example Pod with multiple secrets with a non-default permission mode set. +#### Example configuration: secrets with a non-default permission mode set {#example-configuration-secrets-nondefault-permission-mode} ```yaml apiVersion: v1 @@ -865,7 +863,7 @@ parameters are nearly the same with two exceptions: When the `TokenRequestProjection` feature is enabled, you can inject the token for the current [service account](/docs/reference/access-authn-authz/authentication/#service-account-tokens) -into a Pod at a specified path. Below is an example: +into a Pod at a specified path. For example: ```yaml apiVersion: v1 @@ -891,8 +889,8 @@ spec: ``` The example Pod has a projected volume containing the injected service account -token. This token can be used by Pod containers to access the Kubernetes API -server, for example. The `audience` field contains the intended audience of the +token. This token can be used by a Pod's containers to access the Kubernetes API +server. The `audience` field contains the intended audience of the token. A recipient of the token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. This field is optional and it defaults to the identifier of the API server. @@ -904,96 +902,61 @@ option for the API server. The `path` field specifies a relative path to the mou of the projected volume. {{< note >}} -A Container using a projected volume source as a [subPath](#using-subpath) volume mount will not +A container using a projected volume source as a [`subPath`](#using-subpath) volume mount will not receive updates for those volume sources. {{< /note >}} -### portworxVolume {#portworxvolume} - -A `portworxVolume` is an elastic block storage layer that runs hyperconverged with -Kubernetes. [Portworx](https://portworx.com/use-case/kubernetes-storage/) 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: k8s.gcr.io/test-webserver - name: test-container - volumeMounts: - - mountPath: /mnt - name: pxvol - volumes: - - name: pxvol - # This Portworx volume must already exist. - portworxVolume: - volumeID: "pxvol" - fsType: "" -``` - -{{< caution >}} -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/{{< param "githubbranch" >}}/staging/volumes/portworx/README.md). - -### quobyte {#quobyte} +### quobyte A `quobyte` volume allows an existing [Quobyte](https://www.quobyte.com) volume to be mounted into your Pod. -{{< caution >}} -You must have your own Quobyte setup running with the volumes +{{< note >}} +You must have your own Quobyte setup and running with the volumes created before you can use it. -{{< /caution >}} +{{< /note >}} Quobyte supports the {{< glossary_tooltip text="Container Storage Interface" term_id="csi" >}}. CSI is the recommended plugin to use Quobyte volumes inside Kubernetes. Quobyte's GitHub project has [instructions](https://github.com/quobyte/quobyte-csi#quobyte-csi) for deploying Quobyte using CSI, along with examples. -### rbd {#rbd} +### rbd An `rbd` volume allows a -[Rados Block Device](https://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 +[Rados Block Device](https://ceph.com/docs/master/rbd/rbd/) (RBD) volume to mount into your +Pod. Unlike `emptyDir`, which is erased when a pod is removed, the contents of +an `rbd` volume are preserved and the volume is unmounted. This means that a RBD volume can be pre-populated with data, and that data can -be "handed off" between Pods. +be shared between pods. -{{< caution >}} -You must have your own Ceph installation running before you can use RBD. -{{< /caution >}} +{{< note >}} +You must have a Ceph installation running before you can use RBD. +{{< /note >}} 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. +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. +Simultaneous writers are not allowed. -See the [RBD example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/volumes/rbd) for more details. +See the [RBD example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/volumes/rbd) +for more details. -### scaleIO {#scaleio} +### scaleIO (deprecated) {#scaleio} -ScaleIO is a software-based storage platform that can use existing hardware to +ScaleIO is a software-based storage platform that uses 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)). +plugin allows deployed pods to access existing ScaleIO +volumes. For information about dynamically provisioning new volumes for +persistent volume claims, see +[ScaleIO persistent volumes](/docs/concepts/storage/persistent-volumes/#scaleio). -{{< caution >}} +{{< note >}} You must have an existing ScaleIO cluster already setup and running with the volumes created before you can use them. -{{< /caution >}} +{{< /note >}} -The following is an example of Pod configuration with ScaleIO: +The following example is a Pod configuration with ScaleIO: ```yaml apiVersion: v1 @@ -1020,49 +983,51 @@ spec: fsType: xfs ``` -For further detail, please see the [ScaleIO examples](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/scaleio). +For further details, see the [ScaleIO](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/scaleio) examples. -### secret {#secret} +### 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 +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. -{{< caution >}} -You must create a secret in the Kubernetes API before you can use it. -{{< /caution >}} +{{< note >}} +You must create a Secret in the Kubernetes API before you can use it. +{{< /note >}} {{< note >}} -A Container using a Secret as a [subPath](#using-subpath) volume mount will not +A container using a Secret as a [`subPath`](#using-subpath) volume mount will not receive Secret updates. {{< /note >}} -Secrets are described in more detail [here](/docs/concepts/configuration/secret/). +For more details, see [Configuring Secrets](/docs/concepts/configuration/secret/). ### storageOS {#storageos} A `storageos` volume allows an existing [StorageOS](https://www.storageos.com) -volume to be mounted into your Pod. +volume to mount into your Pod. -StorageOS runs as a Container within your Kubernetes environment, making local +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. +At its core, StorageOS provides block storage to containers, accessible from a file system. The StorageOS Container requires 64-bit Linux and has no additional dependencies. A free developer license is available. {{< caution >}} -You must run the StorageOS Container on each node that wants to +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 >}} +The following example is a Pod configuration with StorageOS: + ```yaml apiVersion: v1 kind: Pod @@ -1091,24 +1056,24 @@ spec: fsType: ext4 ``` -For more information including Dynamic Provisioning and Persistent Volume Claims, please see the +For more information about StorageOS, dynamic provisioning, and PersistentVolumeClaims, see the [StorageOS examples](https://github.com/kubernetes/examples/blob/master/volumes/storageos). ### vsphereVolume {#vspherevolume} {{< note >}} -Prerequisite: Kubernetes with vSphere Cloud Provider configured. For cloudprovider -configuration please refer [vSphere getting started guide](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/). +You must configure the Kubernetes vSphere Cloud Provider. For cloudprovider +configuration, refer to the [vSphere Getting Started guide](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/). {{< /note >}} -A `vsphereVolume` is used to mount a vSphere VMDK Volume into your Pod. The contents +A `vsphereVolume` is used to mount a vSphere VMDK volume into your Pod. The contents of a volume are preserved when it is unmounted. It supports both VMFS and VSAN datastore. -{{< caution >}} -You must create VMDK using one of the following methods before using with Pod. -{{< /caution >}} +{{< note >}} +You must create vSphere VMDK volume using one of the following methods before using with a Pod. +{{< /note >}} -#### Creating a VMDK volume +#### Creating a VMDK volume {#creating-vmdk-volume} Choose one of the following methods to create a VMDK. @@ -1119,6 +1084,7 @@ First ssh into ESX, then use the following command to create a VMDK: ```shell vmkfstools -c 2G /vmfs/volumes/DatastoreName/volumes/myDisk.vmdk ``` + {{% /tab %}} {{% tab name="Create using vmware-vdiskmanager" %}} Use the following command to create a VMDK: @@ -1126,12 +1092,12 @@ Use the following command to create a VMDK: ```shell vmware-vdiskmanager -c -t 0 -s 40GB -a lsilogic myDisk.vmdk ``` + {{% /tab %}} {{< /tabs >}} - -#### vSphere VMDK Example configuration +#### vSphere VMDK configuration example {#vsphere-vmdk-configuration} ```yaml apiVersion: v1 @@ -1153,22 +1119,22 @@ spec: fsType: ext4 ``` -More examples can be found [here](https://github.com/kubernetes/examples/tree/master/staging/volumes/vsphere). +For more information, see the [vSphere volume](https://github.com/kubernetes/examples/tree/master/staging/volumes/vsphere) examples. -#### CSI migration +#### vSphere CSI migration {#vsphere-csi-migration} {{< feature-state for_k8s_version="v1.19" state="beta" >}} -The CSI Migration feature for vsphereVolume, when enabled, shims all plugin operations -from the existing in-tree plugin to the `csi.vsphere.vmware.com` {{< glossary_tooltip text="CSI" term_id="csi" >}} driver. In order to use this feature, the [vSphere CSI -Driver](https://github.com/kubernetes-sigs/vsphere-csi-driver) +The `CSIMigration` feature for `vsphereVolume`, when enabled, redirects all plugin operations +from the existing in-tree plugin to the `csi.vsphere.vmware.com` {{< glossary_tooltip text="CSI" term_id="csi" >}} driver. In order to use this feature, the +[vSphere CSI driver](https://github.com/kubernetes-sigs/vsphere-csi-driver) must be installed on the cluster and the `CSIMigration` and `CSIMigrationvSphere` [feature gates](/docs/reference/command-line-tools-reference/feature-gates/) must be enabled. This also requires minimum vSphere vCenter/ESXi Version to be 7.0u1 and minimum HW Version to be VM version 15. {{< note >}} -The following StorageClass parameters from the built-in vsphereVolume plugin are not supported by the vSphere CSI driver: +The following StorageClass parameters from the built-in `vsphereVolume` plugin are not supported by the vSphere CSI driver: * `diskformat` * `hostfailurestotolerate` @@ -1178,22 +1144,28 @@ The following StorageClass parameters from the built-in vsphereVolume plugin are * `objectspacereservation` * `iopslimit` -Existing volumes created using these parameters will be migrated to the vSphere CSI driver, but new volumes created by the vSphere CSI driver will not be honoring these parameters. +Existing volumes created using these parameters will be migrated to the vSphere CSI driver, +but new volumes created by the vSphere CSI driver will not be honoring these parameters. {{< /note >}} -#### CSI Migration Complete +#### vSphere CSI migration complete {#vsphere-csi-migration-complete} + {{< feature-state for_k8s_version="v1.19" state="beta" >}} -To turn off the vsphereVolume plugin from being loaded by controller manager and kubelet, you need to set this feature flag to true. This requires `csi.vsphere.vmware.com` {{< glossary_tooltip text="CSI" term_id="csi" >}} driver being installed on all worker nodes. +To turn off the `vsphereVolume` plugin from being loaded by the controller manager and the kubelet, you need to set this feature flag to `true`. You must install a `csi.vsphere.vmware.com` {{< glossary_tooltip text="CSI" term_id="csi" >}} driver on all worker nodes. +## Using subPath {#using-subpath} -## Using subPath +Sometimes, it is useful to share one volume for multiple uses in a single pod. +The `volumeMounts.subPath` property specifies a sub-path inside the referenced volume +instead of its root. -Sometimes, it is useful to share one volume for multiple uses in a single Pod. The `volumeMounts.subPath` -property can be used to specify a sub-path inside the referenced volume instead of its root. +The following example shows how to configure a Pod with a LAMP stack (Linux Apache MySQL PHP) +using a single, shared volume. This sample `subPath` configuration is not recommended +for production use. -Here is an example of a Pod with a LAMP stack (Linux Apache Mysql PHP) using a single, shared volume. -The HTML contents are mapped to its `html` folder, and the databases will be stored in its `mysql` folder: +The PHP application's code and assets map to the volume's `html` folder and +the MySQL database is stored in the volume's `mysql` folder. For example: ```yaml apiVersion: v1 @@ -1223,15 +1195,18 @@ spec: claimName: my-lamp-site-data ``` -### Using subPath with expanded environment variables +### Using subPath with expanded environment variables {#using-subpath-expanded-environment} {{< feature-state for_k8s_version="v1.17" state="stable" >}} - -Use the `subPathExpr` field to construct `subPath` directory names from Downward API environment variables. +Use the `subPathExpr` field to construct `subPath` directory names from +downward API environment variables. The `subPath` and `subPathExpr` properties are mutually exclusive. -In this example, a Pod uses `subPathExpr` to create a directory `pod1` within the hostPath volume `/var/log/pods`, using the pod name from the Downward API. The host directory `/var/log/pods/pod1` is mounted at `/logs` in the container. +In this example, a `Pod` uses `subPathExpr` to create a directory `pod1` within +the `hostPath` volume `/var/log/pods`. +The `hostPath` volume takes the `Pod` name from the `downwardAPI`. +The host directory `/var/log/pods/pod1` is mounted at `/logs` in the container. ```yaml apiVersion: v1 @@ -1262,47 +1237,41 @@ spec: ## Resources -The storage media (Disk, SSD, etc.) of an `emptyDir` volume is determined by the +The storage media (such as Disk or SSD) of an `emptyDir` volume is determined by the medium of the filesystem holding the kubelet root dir (typically -`/var/lib/kubelet`). There is no limit on how much space an `emptyDir` or -`hostPath` volume can consume, and no isolation between Containers or between -Pods. +`/var/lib/kubelet`). There is no limit on how much space an `emptyDir` or +`hostPath` volume can consume, and no isolation between containers or between +pods. -In the future, we expect that `emptyDir` and `hostPath` volumes will be able to -request a certain amount of space using a [resource](/docs/concepts/configuration/manage-resources-containers/) -specification, and to select the type of media to use, for clusters that have -several media types. +To learn about requesting space using a resource specification, see +[how to manage resources](/docs/concepts/configuration/manage-resources-containers/). -## Out-of-Tree Volume Plugins +## Out-of-tree volume plugins -The Out-of-tree volume plugins include the Container Storage Interface (CSI) -and FlexVolume. They enable storage vendors to create custom storage plugins -without adding them to the Kubernetes repository. +The out-of-tree volume plugins include +{{< glossary_tooltip text="Container Storage Interface" term_id="csi" >}} (CSI) +and FlexVolume. These plugins enable storage vendors to create custom storage plugins +without adding their plugin source code to the Kubernetes repository. -Before the introduction of CSI and FlexVolume, all volume plugins (like -volume types listed above) were "in-tree" meaning they were built, linked, -compiled, and shipped with the core Kubernetes binaries and extend the core -Kubernetes API. This meant that adding a new storage system to Kubernetes (a -volume plugin) required checking code into the core Kubernetes code repository. +Previously, all volume plugins were "in-tree". The "in-tree" plugins were built, linked, compiled, +and shipped with the core Kubernetes binaries. This meant that adding a new storage system to +Kubernetes (a volume plugin) required checking code into the core Kubernetes code repository. Both CSI and FlexVolume allow volume plugins to be developed independent of the Kubernetes code base, and deployed (installed) on Kubernetes clusters as extensions. For storage vendors looking to create an out-of-tree volume plugin, please refer -to [this FAQ](https://github.com/kubernetes/community/blob/master/sig-storage/volume-plugin-faq.md). +to the [volume plugin FAQ](https://github.com/kubernetes/community/blob/master/sig-storage/volume-plugin-faq.md). -### CSI +### csi -[Container Storage Interface](https://github.com/container-storage-interface/spec/blob/master/spec.md) (CSI) -defines a standard interface for container orchestration systems (like +[Container Storage Interface](https://github.com/container-storage-interface/spec/blob/master/spec.md) +(CSI) defines a standard interface for container orchestration systems (like Kubernetes) to expose arbitrary storage systems to their container workloads. Please read the [CSI design proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/container-storage-interface.md) for more information. -CSI support was introduced as alpha in Kubernetes v1.9, moved to beta in -Kubernetes v1.10, and is GA in Kubernetes v1.13. - {{< note >}} Support for CSI spec versions 0.2 and 0.3 are deprecated in Kubernetes v1.13 and will be removed in a future release. @@ -1315,57 +1284,59 @@ deployments steps for each Kubernetes release and a compatibility matrix. {{< /note >}} Once a CSI compatible volume driver is deployed on a Kubernetes cluster, users -may use the `csi` volume type to attach, mount, etc. the volumes exposed by the +may use the `csi` volume type to attach or mount the volumes exposed by the CSI driver. -A `csi` volume can be used in a pod in three different ways: -- through a reference to a [`persistentVolumeClaim`](#persistentvolumeclaim) -- with a [generic ephemeral volume](/docs/concepts/storage/ephemeral-volumes/#generic-ephemeral-volume) (alpha feature) -- with a [CSI ephemeral volume](/docs/concepts/storage/ephemeral-volumes/#csi-ephemeral-volume) if the driver - supports that (beta feature) +A `csi` volume can be used in a Pod in three different ways: + +* through a reference to a [PersistentVolumeClaim](#persistentvolumeclaim) +* with a [generic ephemeral volume](/docs/concepts/storage/ephemeral-volumes/#generic-ephemeral-volume) +(alpha feature) +* with a [CSI ephemeral volume](/docs/concepts/storage/ephemeral-volumes/#csi-ephemeral-volume) +if the driver supports that (beta feature) The following fields are available to storage administrators to configure a CSI persistent volume: -- `driver`: A string value that specifies the name of the volume driver to use. +* `driver`: A string value that specifies the name of the volume driver to use. This value must correspond to the value returned in the `GetPluginInfoResponse` by the CSI driver as defined in the [CSI spec](https://github.com/container-storage-interface/spec/blob/master/spec.md#getplugininfo). It is used by Kubernetes to identify which CSI driver to call out to, and by CSI driver components to identify which PV objects belong to the CSI driver. -- `volumeHandle`: A string value that uniquely identifies the volume. This value +* `volumeHandle`: A string value that uniquely identifies the volume. This value must correspond to the value returned in the `volume.id` field of the `CreateVolumeResponse` by the CSI driver as defined in the [CSI spec](https://github.com/container-storage-interface/spec/blob/master/spec.md#createvolume). The value is passed as `volume_id` on all calls to the CSI volume driver when referencing the volume. -- `readOnly`: An optional boolean value indicating whether the volume is to be +* `readOnly`: An optional boolean value indicating whether the volume is to be "ControllerPublished" (attached) as read only. Default is false. This value is passed to the CSI driver via the `readonly` field in the `ControllerPublishVolumeRequest`. -- `fsType`: If the PV's `VolumeMode` is `Filesystem` then this field may be used +* `fsType`: If the PV's `VolumeMode` is `Filesystem` then this field may be used to specify the filesystem that should be used to mount the volume. If the volume has not been formatted and formatting is supported, this value will be used to format the volume. This value is passed to the CSI driver via the `VolumeCapability` field of `ControllerPublishVolumeRequest`, `NodeStageVolumeRequest`, and `NodePublishVolumeRequest`. -- `volumeAttributes`: A map of string to string that specifies static properties +* `volumeAttributes`: A map of string to string that specifies static properties of a volume. This map must correspond to the map returned in the `volume.attributes` field of the `CreateVolumeResponse` by the CSI driver as defined in the [CSI spec](https://github.com/container-storage-interface/spec/blob/master/spec.md#createvolume). The map is passed to the CSI driver via the `volume_context` field in the `ControllerPublishVolumeRequest`, `NodeStageVolumeRequest`, and `NodePublishVolumeRequest`. -- `controllerPublishSecretRef`: A reference to the secret object containing +* `controllerPublishSecretRef`: A reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI `ControllerPublishVolume` and `ControllerUnpublishVolume` calls. This field is - optional, and may be empty if no secret is required. If the secret object + optional, and may be empty if no secret is required. If the Secret contains more than one secret, all secrets are passed. -- `nodeStageSecretRef`: A reference to the secret object containing +* `nodeStageSecretRef`: A reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI `NodeStageVolume` call. This field is optional, and may be empty if no secret - is required. If the secret object contains more than one secret, all secrets + is required. If the Secret contains more than one secret, all secrets are passed. -- `nodePublishSecretRef`: A reference to the secret object containing +* `nodePublishSecretRef`: A reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI `NodePublishVolume` call. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all @@ -1375,11 +1346,11 @@ persistent volume: {{< feature-state for_k8s_version="v1.18" state="stable" >}} -Vendors with external CSI drivers can implement raw block volumes support +Vendors with external CSI drivers can implement raw block volume support in Kubernetes workloads. -You can [setup your PV/PVC with raw block volume support](/docs/concepts/storage/persistent-volumes/#raw-block-volume-support) -as usual, without any CSI specific changes. +You can set up your +[PersistentVolume/PersistentVolumeClaim with raw block volume support](/docs/concepts/storage/persistent-volumes/#raw-block-volume-support) as usual, without any CSI specific changes. #### CSI ephemeral volumes @@ -1387,107 +1358,105 @@ as usual, without any CSI specific changes. You can directly configure CSI volumes within the Pod specification. Volumes specified in this way are ephemeral and do not -persist across Pod restarts. See [Ephemeral +persist across pod restarts. See [Ephemeral Volumes](/docs/concepts/storage/ephemeral-volumes/#csi-ephemeral-volume) for more information. -#### {{% heading "whatsnext" %}} - -For more information on how to develop a CSI driver, refer to the [kubernetes-csi -documentation](https://kubernetes-csi.github.io/docs/) +For more information on how to develop a CSI driver, refer to the +[kubernetes-csi documentation](https://kubernetes-csi.github.io/docs/) #### Migrating to CSI drivers from in-tree plugins -{{< feature-state for_k8s_version="v1.14" state="alpha" >}} +{{< feature-state for_k8s_version="v1.17" state="alpha" >}} -The CSI Migration feature, when enabled, directs operations against existing in-tree +The `CSIMigration` feature, when enabled, directs operations against existing in-tree plugins to corresponding CSI plugins (which are expected to be installed and configured). -The feature implements the necessary translation logic and shims to re-route the -operations in a seamless fashion. As a result, operators do not have to make any -configuration changes to existing Storage Classes, PVs or PVCs (referring to -in-tree plugins) when transitioning to a CSI driver that supersedes an in-tree plugin. +As a result, operators do not have to make any +configuration changes to existing Storage Classes, PersistentVolumes or PersistentVolumeClaims +(referring to in-tree plugins) when transitioning to a CSI driver that supersedes an in-tree plugin. -In the alpha state, the operations and features that are supported include +The operations and features that are supported include: provisioning/delete, attach/detach, mount/unmount and resizing of volumes. -In-tree plugins that support CSI Migration and have a corresponding CSI driver implemented -are listed in the "Types of Volumes" section above. +In-tree plugins that support `CSIMigration` and have a corresponding CSI driver implemented +are listed in [Types of Volumes](#volume-types). -### FlexVolume {#flexVolume} +### flexVolume FlexVolume is an out-of-tree plugin interface that has existed in Kubernetes since version 1.2 (before CSI). It uses an exec-based model to interface with -drivers. FlexVolume driver binaries must be installed in a pre-defined volume -plugin path on each node (and in some cases master). +drivers. The FlexVolume driver binaries must be installed in a pre-defined volume +plugin path on each node and in some cases the control plane nodes as well. -Pods interact with FlexVolume drivers through the `flexvolume` in-tree plugin. -More details can be found [here](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-storage/flexvolume.md). +Pods interact with FlexVolume drivers through the `flexvolume` in-tree volume plugin. +For more details, see the [FlexVolume](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-storage/flexvolume.md) examples. ## Mount propagation -Mount propagation allows for sharing volumes mounted by a Container to -other Containers in the same Pod, or even to other Pods on the same node. +Mount propagation allows for sharing volumes mounted by a container to +other containers in the same pod, or even to other pods on the same node. -Mount propagation of a volume is controlled by `mountPropagation` field in Container.volumeMounts. -Its values are: +Mount propagation of a volume is controlled by the `mountPropagation` field +in `Container.volumeMounts`. Its values are: - * `None` - This volume mount will not receive any subsequent mounts - that are mounted to this volume or any of its subdirectories by the host. - In similar fashion, no mounts created by the Container will be visible on - the host. This is the default mode. +* `None` - This volume mount will not receive any subsequent mounts + that are mounted to this volume or any of its subdirectories by the host. + In similar fashion, no mounts created by the container will be visible on + the host. This is the default mode. - This mode is equal to `private` mount propagation as described in the - [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) + This mode is equal to `private` mount propagation as described in the + [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) - * `HostToContainer` - This volume mount will receive all subsequent mounts - that are mounted to this volume or any of its subdirectories. +* `HostToContainer` - This volume mount will receive all subsequent mounts + that are mounted to this volume or any of its subdirectories. - In other words, if the host mounts anything inside the volume mount, the - Container will see it mounted there. + In other words, if the host mounts anything inside the volume mount, the + container will see it mounted there. - Similarly, if any Pod with `Bidirectional` mount propagation to the same - volume mounts anything there, the Container with `HostToContainer` mount - propagation will see it. + Similarly, if any Pod with `Bidirectional` mount propagation to the same + volume mounts anything there, the container with `HostToContainer` mount + propagation will see it. - This mode is equal to `rslave` mount propagation as described in the - [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) + This mode is equal to `rslave` mount propagation as described in the + [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) - * `Bidirectional` - This volume mount behaves the same the `HostToContainer` mount. - In addition, all volume mounts created by the Container will be propagated - back to the host and to all Containers of all Pods that use the same volume. +* `Bidirectional` - This volume mount behaves the same the `HostToContainer` mount. + In addition, all volume mounts created by the container will be propagated + back to the host and to all containers of all pods that use the same volume. - A typical use case for this mode is a Pod with a FlexVolume or CSI driver or - a Pod that needs to mount something on the host using a `hostPath` volume. + A typical use case for this mode is a Pod with a FlexVolume or CSI driver or + a Pod that needs to mount something on the host using a `hostPath` volume. - This mode is equal to `rshared` mount propagation as described in the - [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) + This mode is equal to `rshared` mount propagation as described in the + [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) -{{< caution >}} -`Bidirectional` mount propagation can be dangerous. It can damage -the host operating system and therefore it is allowed only in privileged -Containers. Familiarity with Linux kernel behavior is strongly recommended. -In addition, any volume mounts created by Containers in Pods must be destroyed -(unmounted) by the Containers on termination. -{{< /caution >}} + {{< warning >}} + `Bidirectional` mount propagation can be dangerous. It can damage + the host operating system and therefore it is allowed only in privileged + containers. Familiarity with Linux kernel behavior is strongly recommended. + In addition, any volume mounts created by containers in pods must be destroyed + (unmounted) by the containers on termination. + {{< /warning >}} ### Configuration + Before mount propagation can work properly on some deployments (CoreOS, RedHat/Centos, Ubuntu) mount share must be configured correctly in Docker as shown below. -Edit your Docker's `systemd` service file. Set `MountFlags` as follows: +Edit your Docker's `systemd` service file. Set `MountFlags` as follows: + ```shell MountFlags=shared ``` -Or, remove `MountFlags=slave` if present. Then restart the Docker daemon: + +Or, remove `MountFlags=slave` if present. Then restart the Docker daemon: + ```shell sudo systemctl daemon-reload sudo systemctl restart docker ``` - - ## {{% heading "whatsnext" %}} -* Follow an example of [deploying WordPress and MySQL with Persistent Volumes](/docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/). - +Follow an example of [deploying WordPress and MySQL with Persistent Volumes](/docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/). diff --git a/content/en/docs/concepts/workloads/pods/pod-topology-spread-constraints.md b/content/en/docs/concepts/workloads/pods/pod-topology-spread-constraints.md index 09a02d6afc..28b844d474 100644 --- a/content/en/docs/concepts/workloads/pods/pod-topology-spread-constraints.md +++ b/content/en/docs/concepts/workloads/pods/pod-topology-spread-constraints.md @@ -4,11 +4,21 @@ content_type: concept weight: 40 --- +{{< feature-state for_k8s_version="v1.19" state="stable" >}} + + You can use _topology spread constraints_ to control how {{< glossary_tooltip text="Pods" term_id="Pod" >}} are spread across your cluster among failure-domains such as regions, zones, nodes, and other user-defined topology domains. This can help to achieve high availability as well as efficient resource utilization. - +{{< note >}} +In versions of Kubernetes before v1.19, you must enable the `EvenPodsSpread` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) on +the [API server](/docs/concepts/overview/components/#kube-apiserver) and the +[scheduler](/docs/reference/generated/kube-scheduler/) in order to use Pod +topology spread constraints. +{{< /note >}} @@ -295,13 +305,13 @@ apiVersion: kubescheduler.config.k8s.io/v1beta1 kind: KubeSchedulerConfiguration profiles: - pluginConfig: - - name: PodTopologySpread - args: - defaultConstraints: - - maxSkew: 1 - topologyKey: topology.kubernetes.io/zone - whenUnsatisfiable: ScheduleAnyway + - pluginConfig: + - name: PodTopologySpread + args: + defaultConstraints: + - maxSkew: 1 + topologyKey: topology.kubernetes.io/zone + whenUnsatisfiable: ScheduleAnyway ``` {{< note >}} diff --git a/content/en/docs/setup/production-environment/container-runtimes.md b/content/en/docs/setup/production-environment/container-runtimes.md index c702aa5ca7..ae67726b8e 100644 --- a/content/en/docs/setup/production-environment/container-runtimes.md +++ b/content/en/docs/setup/production-environment/container-runtimes.md @@ -189,13 +189,15 @@ Start-Service containerd {{% /tab %}} {{< /tabs >}} -#### systemd +#### systemd {#containerd-systemd} To use the `systemd` cgroup driver in `/etc/containerd/config.toml` with `runc`, set ``` -[plugins.cri] -systemd_cgroup = true +[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc] + ... + [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options] + SystemdCgroup = true ``` When using kubeadm, manually configure the diff --git a/content/en/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md b/content/en/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md index ee1638bbb3..07d5bfb6bd 100644 --- a/content/en/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md +++ b/content/en/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md @@ -125,7 +125,7 @@ There is a [known limitation](/docs/tasks/configure-pod-container/configure-gmsa {{< glossary_tooltip term_id="containerd" text="ContainerD" >}} 1.4.0-beta.2+ can also be used as the container runtime for Windows Kubernetes nodes. -Initial support for ContainerD on Windows was added in Kubernetes v1.18. Progress for ContainerD on Windows can be tracked at [enhancements#1001](https://github.com/kubernetes/enhancements/issues/1001). +Initial support for ContainerD on Windows was added in Kubernetes v1.18. Progress for ContainerD on Windows can be tracked at [enhancements#1001](https://github.com/kubernetes/enhancements/issues/1001). Learn how to [install ContainerD on a Windows](/docs/setup/production-environment/container-runtimes/#install-containerd). @@ -603,7 +603,7 @@ Your main source of help for troubleshooting your Kubernetes cluster should star In a Kubernetes Pod, an infrastructure or "pause" container is first created to host the container endpoint. Containers that belong to the same pod, including infrastructure and worker containers, share a common network namespace and endpoint (same IP and port space). Pause containers are needed to accommodate worker containers crashing or restarting without losing any of the networking configuration. - The "pause" (infrastructure) image is hosted on Microsoft Container Registry (MCR). You can access it using `docker pull mcr.microsoft.com/k8s/core/pause:1.2.0`. For more details, see the [DOCKERFILE](https://github.com/kubernetes-sigs/sig-windows-tools/tree/master/cmd/wincat). + The "pause" (infrastructure) image is hosted on Microsoft Container Registry (MCR). You can access it using `docker pull mcr.microsoft.com/k8s/core/pause:1.2.0`. For more details, see the [DOCKERFILE](https://github.com/kubernetes-sigs/windows-testing/blob/master/images/pause/Dockerfile). ### Further investigation diff --git a/content/en/docs/tasks/inject-data-application/define-environment-variable-container.md b/content/en/docs/tasks/inject-data-application/define-environment-variable-container.md index cbc3c45260..9cefdca03d 100644 --- a/content/en/docs/tasks/inject-data-application/define-environment-variable-container.md +++ b/content/en/docs/tasks/inject-data-application/define-environment-variable-container.md @@ -47,17 +47,10 @@ Pod: envar-demo 1/1 Running 0 9s ``` -1. Get a shell to the container running in your Pod: +1. List the Pod's container environment variables: ```shell - kubectl exec -it envar-demo -- /bin/bash - ``` - -1. In your shell, run the `printenv` command to list the environment variables. - - ```shell - # Run this in the shell inside the container - printenv + kubectl exec envar-demo -- printenv ``` The output is similar to this: @@ -71,8 +64,6 @@ Pod: DEMO_FAREWELL=Such a sweet sorrow ``` -1. To exit the shell, enter `exit`. - {{< note >}} The environment variables set using the `env` or `envFrom` field override any environment variables specified in the container image. @@ -122,4 +113,3 @@ Upon creation, the command `echo Warm greetings to The Most Honorable Kubernetes * Learn about [using secrets as environment variables](/docs/concepts/configuration/secret/#using-secrets-as-environment-variables). * See [EnvVarSource](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#envvarsource-v1-core). - diff --git a/content/en/docs/test.md b/content/en/docs/test.md index 071a873b37..c052cb5f9c 100644 --- a/content/en/docs/test.md +++ b/content/en/docs/test.md @@ -61,9 +61,7 @@ Markdown doesn't have strict rules about how to process lists. When we moved from Jekyll to Hugo, we broke some lists. To fix them, keep the following in mind: -- Make sure you indent sub-list items **4 spaces** rather than the 2 that you - may be used to. Counter-intuitively, you need to indent block-level content - within a list item an extra 4 spaces too. +- Make sure you indent sub-list items **2 spaces**. - To end a list and start another, you need a HTML comment block on a new line between the lists, flush with the left-hand border. The first list won't end @@ -74,10 +72,9 @@ mind: - This is a list item * This is another list item in the same list - You can mix `-` and `*` - - To make a sub-item, indent two tabstops (4 spaces). **This is different - from Jekyll and Kramdown.** - - This is a sub-sub-item. Indent two more tabstops (4 more spaces). - - Another sub-item. + - To make a sub-item, indent two spaces. + - This is a sub-sub-item. Indent two more spaces. + - Another sub-item. @@ -85,15 +82,15 @@ mind: consecutive lists. **The HTML comment needs to be at the left margin.** - Bullet lists can have paragraphs or block elements within them. - Indent the content to be one tab stop beyond the text of the bullet - point. **This paragraph and the code block line up with the second `l` in - `Bullet` above.** + Indent the content to be the same as the first line of the bullet point. + **This paragraph and the code block line up with the first `B` in `Bullet` + above.** - ```bash - ls -l - ``` + ```bash + ls -l + ``` - - And a sub-list after some block-level content + - And a sub-list after some block-level content - A bullet list item can contain a numbered list. 1. Numbered sub-list item 1 @@ -116,13 +113,13 @@ mind: two consecutive lists. **The HTML comment needs to be at the left margin.** 2. Numbered lists can have paragraphs or block elements within them. - Just indent the content to be one tab stop beyond the text of the bullet - point. **This paragraph and the code block line up with the `m` in - `Numbered` above.** + Just indent the content to be the same as the first line of the bullet + point. **This paragraph and the code block line up with the `N` in + `Numbered` above.** - ```bash - ls -l - ``` + ```bash + ls -l + ``` - And a sub-list after some block-level content. This is at the same "level" as the paragraph and code block above, despite being indented @@ -178,13 +175,6 @@ back-ticks (code fences) for code blocks.** This allows you to specify the language of the enclosed code, which enables syntax highlighting. It is also more predictable than using indentation. -{{< warning >}} -There is one situation where you need to use indentation for code blocks: when -the contents of the code block contain lines starting with `-` or `*` characters. -This is due to -[blackfriday issue #239](https://github.com/russross/blackfriday/issues/239). -{{< /warning >}} - ``` this is a code block created by back-ticks ``` @@ -241,7 +231,7 @@ character. The square brackets contain the image's alt text. Try to always use alt text so that people using screen readers can get some benefit from the image. -![pencil icon](/static/images/pencil.png) +![pencil icon](/images/pencil.png) To specify extended attributes, such as width, title, caption, etc, use the figure shortcode, @@ -249,17 +239,17 @@ which is preferred to using a HTML `` tag. Also, if you need the image to also be a hyperlink, use the `link` attribute, rather than wrapping the whole figure in Markdown link syntax as shown below. -{{< figure src="/static/images/pencil.png" title="Pencil icon" caption="Image used to illustrate the figure shortcode" width="200px" >}} +{{< figure src="/images/pencil.png" title="Pencil icon" caption="Image used to illustrate the figure shortcode" width="200px" >}} Even if you choose not to use the figure shortcode, an image can also be a link. This time the pencil icon links to the Kubernetes website. Outer square brackets enclose the entire image tag, and the link target is in the parentheses at the end. -[![pencil icon](/static/images/pencil.png)](https://kubernetes.io) +[![pencil icon](/images/pencil.png)](https://kubernetes.io) You can also use HTML for images, but it is not preferred. -pencil icon +pencil icon ## Tables diff --git a/content/fr/docs/concepts/workloads/pods/pod-topology-spread-constraints.md b/content/fr/docs/concepts/workloads/pods/pod-topology-spread-constraints.md index 4e0fddc40b..d1cd1f41e1 100644 --- a/content/fr/docs/concepts/workloads/pods/pod-topology-spread-constraints.md +++ b/content/fr/docs/concepts/workloads/pods/pod-topology-spread-constraints.md @@ -205,13 +205,13 @@ apiVersion: kubescheduler.config.k8s.io/v1alpha2 kind: KubeSchedulerConfiguration profiles: - pluginConfig: - - name: PodTopologySpread - args: - defaultConstraints: - - maxSkew: 1 - topologyKey: failure-domain.beta.kubernetes.io/zone - whenUnsatisfiable: ScheduleAnyway + - pluginConfig: + - name: PodTopologySpread + args: + defaultConstraints: + - maxSkew: 1 + topologyKey: topology.kubernetes.io/zone + whenUnsatisfiable: ScheduleAnyway ``` {{< note >}} diff --git a/content/id/docs/concepts/workloads/pods/pod-topology-spread-constraints.md b/content/id/docs/concepts/workloads/pods/pod-topology-spread-constraints.md index f1d970a473..8c5bb1a227 100644 --- a/content/id/docs/concepts/workloads/pods/pod-topology-spread-constraints.md +++ b/content/id/docs/concepts/workloads/pods/pod-topology-spread-constraints.md @@ -249,13 +249,13 @@ apiVersion: kubescheduler.config.k8s.io/v1alpha2 kind: KubeSchedulerConfiguration profiles: - pluginConfig: - - name: PodTopologySpread - args: - defaultConstraints: - - maxSkew: 1 - topologyKey: failure-domain.beta.kubernetes.io/zone - whenUnsatisfiable: ScheduleAnyway + - pluginConfig: + - name: PodTopologySpread + args: + defaultConstraints: + - maxSkew: 1 + topologyKey: topology.kubernetes.io/zone + whenUnsatisfiable: ScheduleAnyway ``` {{< note >}} diff --git a/content/ko/docs/concepts/workloads/pods/pod-topology-spread-constraints.md b/content/ko/docs/concepts/workloads/pods/pod-topology-spread-constraints.md index 31587a99e6..d5d4490608 100644 --- a/content/ko/docs/concepts/workloads/pods/pod-topology-spread-constraints.md +++ b/content/ko/docs/concepts/workloads/pods/pod-topology-spread-constraints.md @@ -295,13 +295,13 @@ apiVersion: kubescheduler.config.k8s.io/v1beta1 kind: KubeSchedulerConfiguration profiles: - pluginConfig: - - name: PodTopologySpread - args: - defaultConstraints: - - maxSkew: 1 - topologyKey: topology.kubernetes.io/zone - whenUnsatisfiable: ScheduleAnyway + - pluginConfig: + - name: PodTopologySpread + args: + defaultConstraints: + - maxSkew: 1 + topologyKey: topology.kubernetes.io/zone + whenUnsatisfiable: ScheduleAnyway ``` {{< note >}} diff --git a/content/zh/docs/concepts/policy/pod-security-policy.md b/content/zh/docs/concepts/policy/pod-security-policy.md index be7c5a88b5..5d87012e66 100644 --- a/content/zh/docs/concepts/policy/pod-security-policy.md +++ b/content/zh/docs/concepts/policy/pod-security-policy.md @@ -862,7 +862,7 @@ to effectively limit access to the specified `pathPrefix`. {{< warning >}} 容器如果对宿主文件系统拥有不受限制的访问权限，就可以有很多种方式提升自己的特权， -包括读取其他容器中的数据、滥用系统服务（如 `kubelet`）`的凭据信息等。 +包括读取其他容器中的数据、滥用系统服务（如 `kubelet`）的凭据信息等。 由可写入的目录所构造的 `hostPath` 卷能够允许容器写入数据到宿主文件系统， 并且在写入时避开 `pathPrefix` 所设置的目录限制。 diff --git a/content/zh/docs/contribute/localization.md b/content/zh/docs/contribute/localization.md index 3f6788a806..5ad2b88a87 100644 --- a/content/zh/docs/contribute/localization.md +++ b/content/zh/docs/contribute/localization.md @@ -455,7 +455,7 @@ Some language teams have their own language-specific style guide and glossary. F ### 特定语言的样式指南和词汇表 一些语言团队有自己的特定语言样式指南和词汇表。 -例如，请参见[韩语本地化指南](/ko/docs/contribute/localization_ko/)。 +例如，请参见[中文本地化指南](/zh/docs/contribute/localization_zh/)。 + +本节详述文档中文本地化过程中须注意的事项。 +这里列举的内容包含了*中文本地化小组*早期给出的指导性建议和后续实践过程中 +积累的经验。 +在阅读、贡献、评阅中文本地化文档的过程中，如果对本文的指南有任何改进建议， +都请直接提出 PR。我们欢迎任何形式的补充和更正！ + + + +## 一般规定 + +本节列举一些译文中常见问题和约定。 + +### 英文原文的保留 + +为便于译文审查和变更追踪，所有中文本地化 Markdown 文件中都应使用 HTML 注释 +`` 将英文原文逐段注释起来，后跟对应中文译文。例如： + +``` + +中文译文对应 ... +``` + +不建议采用下面的方式注释英文段落，除非英文段落非常非常短： + +``` + +中文译文对应 ... + +``` + +无论英文原文或者中文译文中，都不要保留过多的、不必要的空白行。 + +#### 段落划分 + +请避免大段大段地注释和翻译。一般而言，每段翻译可对应两三个自然段。 +段落过长会导致译文很难评阅。但也不必每个段落都单独翻译。例如： + +``` + +## 概述 {#overview} + +### 概念 {#concept} + +第一段落，不太长。 +``` + +以下风格是不必要的： + +``` + +## 概述 {#overview} + + +### 概念 {#concept} + + +第一段落，不太长。 +``` + +#### 编号列表的处理 + +编号列表需要编号的连续性，处理不好的话可能导致输出结果错误。 +由于有些列表可能很长，一次性等将整个列表注释掉再翻译也不现实。 +推荐采用下面的方式。 + +假定英文为： + +``` +1. Prepare something +1. Followed by a long step with code snippets and notes ... + this is a really long item +1. Another long item ... + .. continues here +1. Almost done ... +``` + +本地化处理： + +``` + +1. 准备工作，... + 这里每行缩进 3 个空格 + + +2. 这里是第二个编号，但需要显式给出数字，不能沿用英文编号。 + 缩进内容同上，3 个空格。 + 即使有三个反引号的代码段或者短代码，都按 3 个空格缩进。 + + +3. 继续列表。 + + 如果条目有多个段落，也要 + 保持缩进对齐以确保排版正确。 + +4. 列表终于结束 +``` + +#### Frontmatter 的处理 + +页面中的 Frontmatter 指的是文件头的两个 `---` 中间的部分。 +对这一部分，解析器有特殊处理，因此不能将英文部分放在前面，中文跟在后面。 +需要将二者顺序颠倒。如下所示： + +``` +--- +title: 译文标题 +type: concept +weight: 30 +--- + + +``` + +这里要注意的是： + +- `title`、`description` 的内容要翻译，其他字段一般不必（甚至不可）翻译。 +- `reviewers` 部分要删除，不然中文译文会转给英文作者来审阅。 + + +#### 短代码（shortcode）处理 + +通过 HTML 注释的短代码仍会被运行，因此需要额外小心。建议处理方式： + +``` + +{{}} +中文译文 +{{}} +``` + +评阅人应该不难理解中英文段落的对应关系。但是如果采用下面的方式，则会出现 +两个 `note`，因此需要避免。这是因为被注释起来的短代码仍会起作用！ + +``` + +{{}} +中文译文 +{{}} +``` + +### 译与不译 + +#### 资源名称或字段不译 + +根据英文原文写作风格约定【也在持续修订改进】，对 Kubernetes 中的 API +资源均按其规范中所给的大小写形式书写，例如：英文中会使用 Deployment 而不是 +deployment 来表示名为 "Deployment" 的 API 资源类型和对象实例。 + +对这类词语，一般不应翻译。 + +{{< note >}} +英文原文在这方面并不严谨，译者或中文译文的评阅者要非常留心。 +比如 Secret 资源，很多时候被误写为 secret。这时在本地化版本中一定 +不能译为“秘密”，以免与原文的语义不符。 +{{< /note >}} + +#### 代码中的注释 + +一般而言，代码中的注释需要翻译，包括存放在 `content/zh/examples/` 目录下 +的清单文件中的注释。 + + +#### 出站链接 + +如果超级链接的目标是 Kubernetes 网站之外的纯英文网页，链接中的内容*可以*不翻译。 +例如： + +``` + +请参阅 [installation caveats](https://acme.com/docs/v1/caveats) ... +``` + +注意，这里的 `installation` 与 `参阅` 之间留白，因为解析后属于中英文混排的情况。 + +### 标点符号 + +译文中标点符号要使用全角字符，除非以下两种情况： + +- 标点符号是英文命令的一部分； +- 标点符号是 Markdown 语法的一部分。 + +英文排比句式中采用的逗号，在译文中要使用顿号代替，复合中文书写习惯。 + +## 关于链接 + +### 链接锚点 + +英文 Markdown 中的各级标题会自动生成锚点，以便从其他页面中链接。 +在译为中文后，相应的链接必然会失效。为防止这类问题，建议在翻译 +各级标题时，使用英文方式显式给出链接锚点。例如： + +``` + +### 创建 Pod {#create-a-pod} +``` + +此类问题对于概念部分的页面最为突出，需要格外注意。 + + +### 中文链接目标 + +由于大部分页面已经完成中文本地化，这意味着很多链接可以使用中文版本作为目标。 +例如： + +``` + +更多的信息可参考[卷](/zh/docs/concepts/storage/)页面。 +``` + +如果对应目标页面尚未本地化，建议登记一个 Issue。 + +{{< note >}} +Website 的仓库中 `scripts/linkchecker.py` 是一个工具，可用来检查页面中的链接。 +例如，下面的命令检查中文本地化目录 `/content/zh/docs/concepts/containers/` +中所有 Markdown 文件中的链接合法性： + +``` +./scripts/linkchecker.py -l zh -f /docs/concepts/containers/**/*.md +``` +{{< /note >}} + +## 排版格式 + +以下为译文 Markdown 排版格式要求： + +- 中英文之间留一个空格 + * 这里的“英文”包括以英文呈现的超级链接 + * 这里的中文、英文都不包括标点符号 +- 译文 Markdown 中不要使用长行，应适当断行。 + * 可根据需要在 80-120 列断行 + * 最好结合句子的边界断行，即一句话在一行，不必留几个字转到下一行 + * 超级链接文字一般较长，可独立成行 + +{{< warning >}} +我们注意到有些贡献者可能使用了某种自动化工具，在 Markdown 英文原文中自动 +添加空格。虽然这些工具可一定程度提高效率，仍然需要提请作者注意，某些工具 +所作的转换可能是不对的，例如将 `foo=bar` 转换为 `foo = bar`、将 +`），另一些文字` 转换为 `） ，另一些文字` 等等，甚至将超级链接中的半角 +井号（`#`）转换为全角，导致链接失效。 +{{< /warning >}} + +英文中 "you" 翻译成 "你" 不必是 “您" +文章内的链接用英文例如 (#deploying )，在对应的标题上后面加上 {#deploying} + + +## 术语 + +### 术语拼写 + +按中文译文习惯，尽量不要在中文译文中使用首字母小写的拼写。例如： + +``` +列举所有 pods，查看其创建时间 ... [No] +列举所有 Pod，查看其创建时间 ... [Yes] +``` + +*第一次*使用首字母缩写时，应标注其全称和中文译文。例如： + +``` +你可以创建一个 Pod 干扰预算（Pod Disruption Budget，PDB）来解决这一问题。 +所谓 PDB 实际上是 ... +``` + +对于某些特定于 Kubernetes 语境的术语，也应在*第一次*出现在页面中时给出其英文原文， +以便读者对照阅读。例如： + +``` +镜像策略（Image Policy）用来控制集群可拉取的镜像仓库（Image Registry）源。 +``` + +### 术语对照 + +本节列举常见术语的统一译法。除极个别情况，对于专业术语应使用本节所列举的译法： + +- API Server，API 服务器 +- GA (general availability)，正式发布 +- addons，插件 +- admission controller，准入控制器 +- affinity，亲和性 +- annotation，注解 +- anti-affinity，反亲和性 +- attach，挂接 +- autoscale，自动扩缩容 +- bearer token，持有者令牌 +- capabilities权能字 + * 当泛指某主体执行某操作的能力时，可直译为“能力” + * 当特指 Linux 操作系统上的[权限控制](http://man7.org/linux/man-pages/man7/capabilities.7.html)机制时，译为“权能字” +- certificate authority，证书机构 +- certificate，证书 +- claim，申领 +- cloud provider + * 当用来指代下层云服务的提供厂商时，译为“云服务供应商” + * 当特指 Kubernetes 中对不同云平台的支持时，可酌情译为“云驱动” +- cluster，集群 +- condition + * 大多数上下文中，可译为“条件” + * 在讨论 Kubernetes 资源的 condition 时，应译为“状况” +- control loop，控制回路 +- control plane，控制平面，或控制面 +- controller，控制器 +- controller manager，控制器管理器 +- credential，登录凭据，凭据 +- custom，定制，或自定义 +- daemon，守护进程 +- dashboard，仪表板 +- dependent，附属或附属者 +- deprecated，已弃用的 +- deprecation，弃用 +- desired，预期的 +- desired state，预期状态 +- detach，解除挂接 +- distribution，发行版本 +- disruption，干扰（请勿译为“中断”） +- drain，腾空 +- endpoint，端点 +- egress，出站 +- evict，驱逐 +- eviction，驱逐 +- feature gate，特性门控 +- federation，联邦 +- flags，命令行参数，参数 +- grace period，宽限期限 +- graceful termination，体面终止 +- hairpin，发夹 +- hash，哈希 +- headless service，无头服务 +- healthcheck，健康检查 +- hook，回调 +- host，主机，宿主机 +- hosting，托管 +- idempotent，幂等的 +- image，镜像 +- image registry，镜像仓库 +- ingress，入站 +- init container，Init 容器 +- key + * 在加密解密、安全认证上下文中，译为密钥 + * 在配置文件、数据结构上下文中，译为主键，或键 +- label，标签 +- label selector，标签选择算符 +- lifecycle，生命周期 +- limit，限制，限值 +- liveness probe，存活态探针 +- load balance，负载均衡 +- load balancer，负载均衡器 +- log flush，清刷日志数据 +- loopback，本地回路 +- manifest，清单，清单文件 +- master node，主控节点 +- metric + * 用来指代被测量的数据源时，译为指标 + * 用来指代测量观测结果时，译为度量值 +- mount，挂载 +- namespace，名字空间，命名空间 +- orphans，孤立或孤立的 +- override，覆写 +- owner，所有者，属主 +- pending，悬决的 +- persistent volume，持久卷 +- persistent volume claim，持久卷申领 +- pipeline，流水线 +- prerequisites，依赖，前提条件（根据上下文判断） +- priority class，优先级类 +- probe，探针 +- provision，供应 +- pull，拉取 +- push，推送 +- quota，配额 +- readiness probe，就绪态探针 +- replica，副本 +- repo，仓库 +- repository，仓库 +- revision，修订版本 +- role，角色 +- role binding，角色绑定 +- rolling update，滚动更新 +- rollout，上线 +- rotate，轮换 +- round robin，轮转 +- runtime，运行时 +- scale in/out，横向缩容/扩容 +- scale up/down，纵向扩容/缩容 +- scale + * 做动词用时，译为“扩缩”，或者“改变...的规模” + * 做名词用时，译为“规模” +- scheduler，调度器 +- service，服务 +- service account，服务账号 +- service account token，服务账号令牌 +- service discovery，服务发现 +- service mesh，服务网格 +- session，会话 +- sidecar，挂斗 +- skew，偏移 +- spec，规约 +- specification，规约 +- startup probe，启动探针 +- stateless，无状态的 +- static pod，静态 Pod +- stderr，标准错误输出 +- stdin，标准输入 +- stdout，标准输出 +- storage class，存储类 +- taint，污点 +- threshold，阈值 +- toleration，容忍度 +- topology，拓扑 +- topology spread constraint，拓扑分布约束 +- traffic，流量 + * 在某些上下文中，可以根据情况译为“服务请求”，“服务响应” +- unmount，卸载 +- use case，用例，使用场景 +- volume，卷 +- worker node，工作节点 +- workload，工作负载 diff --git a/content/zh/docs/reference/kubectl/cheatsheet.md b/content/zh/docs/reference/kubectl/cheatsheet.md index 0ede5fb604..1c351a7eab 100644 --- a/content/zh/docs/reference/kubectl/cheatsheet.md +++ b/content/zh/docs/reference/kubectl/cheatsheet.md @@ -24,7 +24,7 @@ See also: [Kubectl Overview](/docs/reference/kubectl/overview/) and [JsonPath Gu This page is an overview of the `kubectl` command. --> -另见: [Kubectl 概述](/docs/reference/kubectl/overview/) 和 [JsonPath 指南](/docs/reference/kubectl/jsonpath)。 +另见: [Kubectl 概述](/zh/docs/reference/kubectl/overview/) 和 [JsonPath 指南](/zh/docs/reference/kubectl/jsonpath)。 本页面是 `kubectl` 命令的概述。 @@ -85,15 +85,15 @@ detailed config file information. ## Kubectl 上下文和配置 设置 `kubectl` 与哪个 Kubernetes 集群进行通信并修改配置信息。查看 -[使用 kubeconfig 跨集群授权访问](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) +[使用 kubeconfig 跨集群授权访问](/zh/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) 文档获取配置文件详细信息。 - @@ -402,7 +402,7 @@ kubectl diff -f ./my-manifest.yaml ```bash kubectl set image deployment/frontend www=image:v2 # 滚动更新 "frontend" Deployment 的 "www" 容器镜像 -kubectl rollout history deployment/frontend # 检查 Deployment 的历史记录，包括版本 +kubectl rollout history deployment/frontend # 检查 Deployment 的历史记录，包括版本 kubectl rollout undo deployment/frontend # 回滚到上次部署版本 kubectl rollout undo deployment/frontend --to-revision=2 # 回滚到特定部署版本 kubectl rollout status -w deployment/frontend # 监视 "frontend" Deployment 的滚动升级状态直到完成 @@ -465,13 +465,13 @@ kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/ # Disable a deployment livenessProbe using a json patch with positional arrays kubectl patch deployment valid-deployment --type json -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]' -# Add a new element to a positional array +# Add a new element to a positional array kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]' ``` --> ```bash # 部分更新某节点 -kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}' +kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}' # 更新容器的镜像；spec.containers[*].name 是必须的。因为它是一个合并性质的主键。 kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}' @@ -482,7 +482,7 @@ kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/ # 使用带位置数组的 JSON patch 禁用某 Deployment 的 livenessProbe kubectl patch deployment valid-deployment --type json -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]' -# 在带位置数组中添加元素 +# 在带位置数组中添加元素 kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]' ``` @@ -567,7 +567,7 @@ kubectl logs -f my-pod # stream pod logs (stdout) kubectl logs -f my-pod -c my-container # stream pod container logs (stdout, multi-container case) kubectl logs -f -l name=myLabel --all-containers # stream all pods logs with label name=myLabel (stdout) kubectl run -i --tty busybox --image=busybox -- sh # Run pod as interactive shell -kubectl run nginx --image=nginx -n +kubectl run nginx --image=nginx -n mynamespace # Run pod nginx in a specific namespace kubectl run nginx --image=nginx # Run pod nginx and write its spec into a file called pod.yaml --dry-run=client -o yaml > pod.yaml @@ -641,7 +641,7 @@ kubectl taint nodes foo dedicated=special-user:NoSchedule -列出所支持的全部资源类型和它们的简称、[API 组](/docs/concepts/overview/kubernetes-api/#api-groups), 是否是[名字空间作用域](/docs/concepts/overview/working-with-objects/namespaces) 和 [Kind](/docs/concepts/overview/working-with-objects/kubernetes-objects)。 +列出所支持的全部资源类型和它们的简称、[API 组](/zh/docs/concepts/overview/kubernetes-api/#api-groups), 是否是[名字空间作用域](/zh/docs/concepts/overview/working-with-objects/namespaces) 和 [Kind](/zh/docs/concepts/overview/working-with-objects/kubernetes-objects)。 ```bash kubectl api-resources @@ -697,8 +697,8 @@ utput format | Description `-o=custom-columns=` | 使用逗号分隔的自定义列来打印表格 `-o=custom-columns-file=` | 使用 `` 文件中的自定义列模板打印表格 `-o=json` | 输出 JSON 格式的 API 对象 -`-o=jsonpath=