Merge remote-tracking branch 'upstream/master' into dev-1.18

2020-03-05 13:57:29 -08:00
parent 95a6e055d8 80d26d3b7d
commit b02c571a7c
37 changed files with 358 additions and 67 deletions
@@ -131,6 +131,8 @@ Kubernetes creates a node object internally (the representation), and
 validates the node by health checking based on the `metadata.name` field. If the node is valid -- that is, if all necessary
 services are running -- it is eligible to run a pod. Otherwise, it is
 ignored for any cluster activity until it becomes valid.
+The name of a Node object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

 {{< note >}}
 Kubernetes keeps the object for the invalid node and keeps checking to see whether it becomes valid.
@@ -68,6 +68,8 @@ echo -n '1f2d1e2e67df' > ./password.txt

 The `kubectl create secret` command packages these files into a Secret and creates
 the object on the API server.
+The name of a Secret object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

 ```shell
 kubectl create secret generic db-user-pass --from-file=./username.txt --from-file=./password.txt
@@ -137,8 +139,10 @@ See [decoding a secret](#decoding-a-secret) to learn how to view the contents of
 #### Creating a Secret manually

 You can also create a Secret in a file first, in JSON or YAML format,
-and then create that object. The
-[Secret](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#secret-v1-core)
+and then create that object.
+The name of a Secret object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
+The [Secret](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#secret-v1-core)
 contains two maps:
 `data` and `stringData`. The `data` field is used to store arbitrary data, encoded using
 base64. The `stringData` field is provided for convenience, and allows you to provide
@@ -33,7 +33,7 @@ one of its arguments.
 A limit range is enforced in a particular namespace when there is a
 `LimitRange` object in that namespace.

-### Overview of Limit Range:
+### Overview of Limit Range

 - The administrator creates one `LimitRange` in one namespace.
 - Users create resources like Pods, Containers, and PersistentVolumeClaims in the namespace.
@@ -43,7 +43,6 @@ A limit range is enforced in a particular namespace when there is a
  requests or limits for those values; otherwise, the system may reject pod creation.
 - LimitRange validations occurs only at Pod Admission stage, not on Running pods.

-
 Examples of policies that could be created using limit range are:

 - In a 2 node cluster with a capacity of 8 GiB RAM, and 16 cores, constrain Pods in a namespace to request 100m and not exceeds 500m for CPU , request 200Mi and not exceed 600Mi
@@ -76,6 +75,8 @@ Here is the configuration file for a LimitRange object:
 {{< codenew file="admin/resource/limit-mem-cpu-container.yaml" >}}

 This object defines minimum and maximum Memory/CPU limits,  default cpu/Memory requests  and default limits for CPU/Memory resources to be apply to containers.
+The name of a LimitRange object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

 Create the `limit-mem-cpu-per-container` LimitRange in the `limitrange-demo` namespace with the following kubectl command:

@@ -37,6 +37,9 @@ Resource quotas work like this:
  the `LimitRanger` admission controller to force defaults for pods that make no compute resource requirements.
  See the [walkthrough](/docs/tasks/administer-cluster/quota-memory-cpu-namespace/) for an example of how to avoid this problem.

+The name of a `ResourceQuota` object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
+
 Examples of policies that could be created using namespaces and quotas are:

 - In a cluster with a capacity of 32 GiB RAM, and 16 cores, let team A use 20 GiB and 10 cores,
@@ -32,6 +32,8 @@ for a Kubernetes Service when a {{< glossary_tooltip text="selector"
 term_id="selector" >}} is specified. These EndpointSlices will include
 references to any Pods that match the Service selector. EndpointSlices group
 network endpoints together by unique Service and Port combinations.
+The name of a EndpointSlice object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

 As an example, here's a sample EndpointSlice resource for the `example`
 Kubernetes Service.
@@ -78,11 +78,13 @@ spec:
          servicePort: 80
 ```

- As with all other Kubernetes resources, an Ingress needs `apiVersion`, `kind`, and `metadata` fields.
- For general information about working with config files, see [deploying applications](/docs/tasks/run-application/run-stateless-application-deployment/), [configuring containers](/docs/tasks/configure-pod-container/configure-pod-configmap/), [managing resources](/docs/concepts/cluster-administration/manage-deployment/).
+As with all other Kubernetes resources, an Ingress needs `apiVersion`, `kind`, and `metadata` fields.
+The name of an Ingress object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
+For general information about working with config files, see [deploying applications](/docs/tasks/run-application/run-stateless-application-deployment/), [configuring containers](/docs/tasks/configure-pod-container/configure-pod-configmap/), [managing resources](/docs/concepts/cluster-administration/manage-deployment/).
 Ingress frequently uses annotations to configure some options depending on the Ingress controller, an example of which
 is the [rewrite-target annotation](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/rewrite/README.md).
- Different [Ingress controller](/docs/concepts/services-networking/ingress-controllers) support different annotations. Review the documentation for
+Different [Ingress controller](/docs/concepts/services-networking/ingress-controllers) support different annotations. Review the documentation for
 your choice of Ingress controller to learn which annotations are supported.

 The Ingress [spec](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status)
@@ -73,6 +73,8 @@ balancer in between your application and the backend Pods.
 A Service in Kubernetes is a REST object, similar to a Pod.  Like all of the
 REST objects, you can `POST` a Service definition to the API server to create
 a new instance.
+The name of a Service object must be a valid
+[DNS label name](/docs/concepts/overview/working-with-objects/names#dns-label-names).

 For example, suppose you have a set of Pods that each listen on TCP port 9376
 and carry a label `app=MyApp`:
@@ -167,6 +169,9 @@ subsets:
      - port: 9376
 ```

+The name of the Endpoints object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
+
 {{< note >}}
 The endpoint IPs _must not_ be: loopback (127.0.0.0/8 for IPv4, ::1/128 for IPv6), or
 link-local (169.254.0.0/16 and 224.0.0.0/24 for IPv4, fe80::/64 for IPv6).
@@ -41,7 +41,6 @@ resource.

 See the [detailed walkthrough with working examples](/docs/tasks/configure-pod-container/configure-persistent-volume-storage/).

-
 ## Lifecycle of a volume and claim

 PVs are resources in the cluster. PVCs are requests for those resources and also act as claim checks to the resource. The interaction between PVs and PVCs follows this lifecycle:
@@ -51,9 +50,11 @@ PVs are resources in the cluster. PVCs are requests for those resources and also
 There are two ways PVs may be provisioned: statically or dynamically.

 #### Static
+
 A cluster administrator creates a number of PVs. They carry the details of the real storage, which is available for use by cluster users. They exist in the Kubernetes API and are available for consumption.

 #### Dynamic
+
 When none of the static PVs the administrator created match a user's `PersistentVolumeClaim`,
 the cluster may try to dynamically provision a volume specially for the PVC.
 This provisioning is based on `StorageClasses`: the PVC must request a
@@ -286,6 +287,8 @@ Expanding EBS volumes is a time-consuming operation. Also, there is a per-volume
 ## Persistent Volumes

 Each PV contains a spec and status, which is the specification and status of the volume.
+The name of a PersistentVolume object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

 ```yaml
 apiVersion: v1
@@ -440,6 +443,8 @@ The CLI will show the name of the PVC bound to the PV.
 ## PersistentVolumeClaims

 Each PVC contains a spec and status, which is the specification and status of the claim.
+The name of a PersistentVolumeClaim object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

 ```yaml
 apiVersion: v1
@@ -574,6 +579,7 @@ Support for the additional plugins was added in 1.10.
 {{< /note >}}

 ### Persistent Volumes using a Raw Block Volume
+
 ```yaml
 apiVersion: v1
 kind: PersistentVolume
@@ -592,6 +598,7 @@ spec:
    readOnly: false
 ```
 ### Persistent Volume Claim requesting a Raw Block Volume
+
 ```yaml
 apiVersion: v1
 kind: PersistentVolumeClaim
@@ -605,7 +612,9 @@ spec:
    requests:
      storage: 10Gi
 ```
+
 ### Pod specification adding Raw Block Device path in container
+
 ```yaml
 apiVersion: v1
 kind: Pod
@@ -662,6 +671,7 @@ To enable support for restoring a volume from a volume snapshot data source, ena
 `VolumeSnapshotDataSource` feature gate on the apiserver and controller-manager.

 ### Create Persistent Volume Claim from Volume Snapshot
+
 ```yaml
 apiVersion: v1
 kind: PersistentVolumeClaim
@@ -690,6 +700,7 @@ To enable support for cloning a volume from a PVC data source, enable the
 `VolumePVCDataSource` feature gate on the apiserver and controller-manager.

 ### Create Persistent Volume Claim from an existing pvc
+
 ```yaml
 apiVersion: v1
 kind: PersistentVolumeClaim
@@ -60,6 +60,10 @@ spec:
    name: pvc-1
 ```

+{{< note >}}
+You must specify a capacity value for `spec.resources.requests.storage`, and the value you specify must be the same or larger than the capacity of the source volume.
+{{< /note >}}
+
 The result is a new PVC with the name `clone-of-pvc-1` that has the exact same content as the specified source `pvc-1`.

 ## Usage
@@ -27,7 +27,8 @@ that the cron job controller uses.
 {{< /caution >}}

 When creating the manifest for a CronJob resource, make sure the name you provide
-is no longer than 52 characters. This is because the CronJob controller will automatically
+is a valid [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
+The name must be no longer than 52 characters. This is because the CronJob controller will automatically
 append 11 characters to the job name provided and there is a constraint that the
 maximum length of a Job name is no more than 63 characters.

@@ -114,6 +114,7 @@ The output is similar to this:
 ## Writing a Job Spec

 As with all other Kubernetes config, a Job needs `apiVersion`, `kind`, and `metadata` fields.
+Its name must be a valid [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

 A Job also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).

@@ -116,6 +116,8 @@ specifies an expression that just gets the name from each pod in the returned li
 ## Writing a ReplicationController Spec

 As with all other Kubernetes config, a ReplicationController needs `apiVersion`, `kind`, and `metadata` fields.
+The name of a ReplicationController object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
 For general information about working with config files, see [object management ](/docs/concepts/overview/working-with-objects/object-management/).

 A ReplicationController also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
@@ -203,5 +203,7 @@ Your container runtime must support the concept of a privileged container for th
 Pod is a top-level resource in the Kubernetes REST API.
 The [Pod API object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#pod-v1-core) definition
 describes the object in detail.
+When creating the manifest for a Pod object, make sure the name specified is a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

 {{% /capture %}}