From f9ebc90ff71ed966852b1133f1a14d50c6b69a7f Mon Sep 17 00:00:00 2001 From: Daniel Wright Date: Mon, 11 Jul 2022 08:41:04 -0700 Subject: [PATCH] [en] update en docs to use recommended labels --- .../docs/concepts/configuration/overview.md | 2 +- .../services-networking/dual-stack.md | 18 ++++---- .../service-traffic-policy.md | 2 +- .../concepts/services-networking/service.md | 45 +++++++++---------- .../workloads/pods/init-containers.md | 6 +-- .../debug-application/debug-statefulset.md | 4 +- .../docs/tasks/network/validate-dual-stack.md | 18 ++++---- .../run-application/delete-stateful-set.md | 10 ++--- .../networking/dual-stack-default-svc.yaml | 4 +- .../dual-stack-ipfamilies-ipv6.yaml | 4 +- .../networking/dual-stack-ipv6-svc.yaml | 4 +- .../dual-stack-prefer-ipv6-lb-svc.yaml | 4 +- .../dual-stack-preferred-ipfamilies-svc.yaml | 4 +- .../networking/dual-stack-preferred-svc.yaml | 4 +- 14 files changed, 64 insertions(+), 65 deletions(-) diff --git a/content/en/docs/concepts/configuration/overview.md b/content/en/docs/concepts/configuration/overview.md index a4dd5c5901..5dc5a64826 100644 --- a/content/en/docs/concepts/configuration/overview.md +++ b/content/en/docs/concepts/configuration/overview.md @@ -63,7 +63,7 @@ DNS server watches the Kubernetes API for new `Services` and creates a set of DN ## Using Labels -- Define and use [labels](/docs/concepts/overview/working-with-objects/labels/) that identify __semantic attributes__ of your application or Deployment, such as `{ app: myapp, tier: frontend, phase: test, deployment: v3 }`. You can use these labels to select the appropriate Pods for other resources; for example, a Service that selects all `tier: frontend` Pods, or all `phase: test` components of `app: myapp`. See the [guestbook](https://github.com/kubernetes/examples/tree/master/guestbook/) app for examples of this approach. +- Define and use [labels](/docs/concepts/overview/working-with-objects/labels/) that identify __semantic attributes__ of your application or Deployment, such as `{ app.kubernetes.io/name: MyApp, tier: frontend, phase: test, deployment: v3 }`. You can use these labels to select the appropriate Pods for other resources; for example, a Service that selects all `tier: frontend` Pods, or all `phase: test` components of `app.kubernetes.io/name: MyApp`. See the [guestbook](https://github.com/kubernetes/examples/tree/master/guestbook/) app for examples of this approach. A Service can be made to span multiple Deployments by omitting release-specific labels from its selector. When you need to update a running service without downtime, use a [Deployment](/docs/concepts/workloads/controllers/deployment/). diff --git a/content/en/docs/concepts/services-networking/dual-stack.md b/content/en/docs/concepts/services-networking/dual-stack.md index 921d69e8fb..1716d7483b 100644 --- a/content/en/docs/concepts/services-networking/dual-stack.md +++ b/content/en/docs/concepts/services-networking/dual-stack.md @@ -37,7 +37,7 @@ IPv4/IPv6 dual-stack on your Kubernetes cluster provides the following features: The following prerequisites are needed in order to utilize IPv4/IPv6 dual-stack Kubernetes clusters: -* Kubernetes 1.20 or later +* Kubernetes 1.20 or later For information about using dual-stack services with earlier Kubernetes versions, refer to the documentation for that version @@ -95,7 +95,7 @@ set the `.spec.ipFamilyPolicy` field to one of the following values: If you would like to define which IP family to use for single stack or define the order of IP families for dual-stack, you can choose the address families by setting an optional field, -`.spec.ipFamilies`, on the Service. +`.spec.ipFamilies`, on the Service. {{< note >}} The `.spec.ipFamilies` field is immutable because the `.spec.ClusterIP` cannot be reallocated on a @@ -133,11 +133,11 @@ These examples demonstrate the behavior of various dual-stack Service configurat address assignments. The field `.spec.ClusterIPs` is the primary field, and contains both assigned IP addresses; `.spec.ClusterIP` is a secondary field with its value calculated from `.spec.ClusterIPs`. - + * For the `.spec.ClusterIP` field, the control plane records the IP address that is from the - same address family as the first service cluster IP range. + same address family as the first service cluster IP range. * On a single-stack cluster, the `.spec.ClusterIPs` and `.spec.ClusterIP` fields both only list - one address. + one address. * On a cluster with dual-stack enabled, specifying `RequireDualStack` in `.spec.ipFamilyPolicy` behaves the same as `PreferDualStack`. @@ -174,7 +174,7 @@ dual-stack.) kind: Service metadata: labels: - app: MyApp + app.kubernetes.io/name: MyApp name: my-service spec: clusterIP: 10.0.197.123 @@ -188,7 +188,7 @@ dual-stack.) protocol: TCP targetPort: 80 selector: - app: MyApp + app.kubernetes.io/name: MyApp type: ClusterIP status: loadBalancer: {} @@ -214,7 +214,7 @@ dual-stack.) kind: Service metadata: labels: - app: MyApp + app.kubernetes.io/name: MyApp name: my-service spec: clusterIP: None @@ -228,7 +228,7 @@ dual-stack.) protocol: TCP targetPort: 80 selector: - app: MyApp + app.kubernetes.io/name: MyApp ``` #### Switching Services between single-stack and dual-stack diff --git a/content/en/docs/concepts/services-networking/service-traffic-policy.md b/content/en/docs/concepts/services-networking/service-traffic-policy.md index b9abe34b3f..8755b5298b 100644 --- a/content/en/docs/concepts/services-networking/service-traffic-policy.md +++ b/content/en/docs/concepts/services-networking/service-traffic-policy.md @@ -43,7 +43,7 @@ metadata: name: my-service spec: selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80 diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index c88375164b..eda3b6b9b3 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -75,7 +75,7 @@ The name of a Service object must be a valid [RFC 1035 label name](/docs/concepts/overview/working-with-objects/names#rfc-1035-label-names). For example, suppose you have a set of Pods where each listens on TCP port 9376 -and contains a label `app=MyApp`: +and contains a label `app.kubernetes.io/name=MyApp`: ```yaml apiVersion: v1 @@ -84,7 +84,7 @@ metadata: name: my-service spec: selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80 @@ -92,7 +92,7 @@ spec: ``` This specification creates a new Service object named "my-service", which -targets TCP port 9376 on any Pod with the `app=MyApp` label. +targets TCP port 9376 on any Pod with the `app.kubernetes.io/name=MyApp` label. Kubernetes assigns this Service an IP address (sometimes called the "cluster IP"), which is used by the Service proxies @@ -126,7 +126,7 @@ spec: ports: - containerPort: 80 name: http-web-svc - + --- apiVersion: v1 kind: Service @@ -144,9 +144,9 @@ spec: This works even if there is a mixture of Pods in the Service using a single -configured name, with the same network protocol available via different -port numbers. This offers a lot of flexibility for deploying and evolving -your Services. For example, you can change the port numbers that Pods expose +configured name, with the same network protocol available via different +port numbers. This offers a lot of flexibility for deploying and evolving +your Services. For example, you can change the port numbers that Pods expose in the next version of your backend software, without breaking clients. The default protocol for Services is TCP; you can also use any other @@ -159,7 +159,7 @@ Each port definition can have the same `protocol`, or a different one. ### Services without selectors Services most commonly abstract access to Kubernetes Pods thanks to the selector, -but when used with a corresponding Endpoints object and without a selector, the Service can abstract other kinds of backends, +but when used with a corresponding Endpoints object and without a selector, the Service can abstract other kinds of backends, including ones that run outside the cluster. For example: * You want to have an external database cluster in production, but in your @@ -222,10 +222,10 @@ In the example above, traffic is routed to the single endpoint defined in the YAML: `192.0.2.42:9376` (TCP). {{< note >}} -The Kubernetes API server does not allow proxying to endpoints that are not mapped to -pods. Actions such as `kubectl proxy ` where the service has no -selector will fail due to this constraint. This prevents the Kubernetes API server -from being used as a proxy to endpoints the caller may not be authorized to access. +The Kubernetes API server does not allow proxying to endpoints that are not mapped to +pods. Actions such as `kubectl proxy ` where the service has no +selector will fail due to this constraint. This prevents the Kubernetes API server +from being used as a proxy to endpoints the caller may not be authorized to access. {{< /note >}} An ExternalName Service is a special case of Service that does not have @@ -289,7 +289,7 @@ There are a few reasons for using proxying for Services: Later in this page you can read about various kube-proxy implementations work. Overall, you should note that, when running `kube-proxy`, kernel level rules may be -modified (for example, iptables rules might get created), which won't get cleaned up, +modified (for example, iptables rules might get created), which won't get cleaned up, in some cases until you reboot. Thus, running kube-proxy is something that should only be done by an administrator which understands the consequences of having a low level, privileged network proxying service on a computer. Although the `kube-proxy` @@ -423,7 +423,7 @@ metadata: name: my-service spec: selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - name: http protocol: TCP @@ -636,7 +636,7 @@ to specify IP address ranges that kube-proxy should consider as local to this no For example, if you start kube-proxy with the `--nodeport-addresses=127.0.0.0/8` flag, kube-proxy only selects the loopback interface for NodePort Services. -The default for `--nodeport-addresses` is an empty list. +The default for `--nodeport-addresses` is an empty list. his means that kube-proxy should consider all available network interfaces for NodePort. (That's also compatible with earlier Kubernetes releases). @@ -666,7 +666,7 @@ metadata: spec: type: NodePort selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: # By default and for convenience, the `targetPort` is set to the same value as the `port` field. - port: 80 @@ -692,7 +692,7 @@ metadata: name: my-service spec: selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80 @@ -765,13 +765,13 @@ You must explicitly remove the `nodePorts` entry in every Service port to de-all `spec.loadBalancerClass` enables you to use a load balancer implementation other than the cloud provider default. By default, `spec.loadBalancerClass` is `nil` and a `LoadBalancer` type of Service uses the cloud provider's default load balancer implementation if the cluster is configured with -a cloud provider using the `--cloud-provider` component flag. +a cloud provider using the `--cloud-provider` component flag. If `spec.loadBalancerClass` is specified, it is assumed that a load balancer implementation that matches the specified class is watching for Services. Any default load balancer implementation (for example, the one provided by the cloud provider) will ignore Services that have this field set. `spec.loadBalancerClass` can be set on a Service of type `LoadBalancer` only. -Once set, it cannot be changed. +Once set, it cannot be changed. The value of `spec.loadBalancerClass` must be a label-style identifier, with an optional prefix such as "`internal-vip`" or "`example.com/internal-vip`". Unprefixed names are reserved for end-users. @@ -1073,7 +1073,7 @@ There are other annotations to manage Classic Elastic Load Balancers that are de # A list of existing security groups to be configured on the ELB created. Unlike the annotation # service.beta.kubernetes.io/aws-load-balancer-extra-security-groups, this replaces all other - # security groups previously assigned to the ELB and also overrides the creation + # security groups previously assigned to the ELB and also overrides the creation # of a uniquely generated security group for this ELB. # The first security group ID on this list is used as a source to permit incoming traffic to # target worker nodes (service traffic and health checks). @@ -1087,7 +1087,7 @@ There are other annotations to manage Classic Elastic Load Balancers that are de # generated security group in place, this ensures that every ELB # has a unique security group ID and a matching permit line to allow traffic to the target worker nodes # (service traffic and health checks). - # Security groups defined here can be shared between services. + # Security groups defined here can be shared between services. service.beta.kubernetes.io/aws-load-balancer-extra-security-groups: "sg-53fae93f,sg-42efd82e" # A comma separated list of key-value pairs which are used @@ -1263,7 +1263,7 @@ metadata: name: my-service spec: selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - name: http protocol: TCP @@ -1481,4 +1481,3 @@ followed by the data from the client. * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) * Read about [Ingress](/docs/concepts/services-networking/ingress/) * Read about [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/) - diff --git a/content/en/docs/concepts/workloads/pods/init-containers.md b/content/en/docs/concepts/workloads/pods/init-containers.md index 61b90d17d0..85c5ec413b 100644 --- a/content/en/docs/concepts/workloads/pods/init-containers.md +++ b/content/en/docs/concepts/workloads/pods/init-containers.md @@ -28,7 +28,7 @@ Init containers are exactly like regular containers, except: * Init containers always run to completion. * Each init container must complete successfully before the next one starts. -If a Pod's init container fails, the kubelet repeatedly restarts that init container until it succeeds. +If a Pod's init container fails, the kubelet repeatedly restarts that init container until it succeeds. However, if the Pod has a `restartPolicy` of Never, and an init container fails during startup of that Pod, Kubernetes treats the overall Pod as failed. To specify an init container for a Pod, add the `initContainers` field into @@ -115,7 +115,7 @@ kind: Pod metadata: name: myapp-pod labels: - app: myapp + app.kubernetes.io/name: MyApp spec: containers: - name: myapp-container @@ -159,7 +159,7 @@ The output is similar to this: Name: myapp-pod Namespace: default [...] -Labels: app=myapp +Labels: app.kubernetes.io/name=MyApp Status: Pending [...] Init Containers: diff --git a/content/en/docs/tasks/debug/debug-application/debug-statefulset.md b/content/en/docs/tasks/debug/debug-application/debug-statefulset.md index 73c0d0c78a..428b8d0ee5 100644 --- a/content/en/docs/tasks/debug/debug-application/debug-statefulset.md +++ b/content/en/docs/tasks/debug/debug-application/debug-statefulset.md @@ -24,11 +24,11 @@ This task shows you how to debug a StatefulSet. ## Debugging a StatefulSet -In order to list all the pods which belong to a StatefulSet, which have a label `app=myapp` set on them, +In order to list all the pods which belong to a StatefulSet, which have a label `app.kubernetes.io/name=MyApp` set on them, you can use the following: ```shell -kubectl get pods -l app=myapp +kubectl get pods -l app.kubernetes.io/name=MyApp ``` If you find that any Pods listed are in `Unknown` or `Terminating` state for an extended period of time, diff --git a/content/en/docs/tasks/network/validate-dual-stack.md b/content/en/docs/tasks/network/validate-dual-stack.md index 33a8d39091..a27fc8050d 100644 --- a/content/en/docs/tasks/network/validate-dual-stack.md +++ b/content/en/docs/tasks/network/validate-dual-stack.md @@ -134,7 +134,7 @@ spec: protocol: TCP targetPort: 9376 selector: - app: MyApp + app.kubernetes.io/name: MyApp sessionAffinity: None type: ClusterIP status: @@ -158,7 +158,7 @@ apiVersion: v1 kind: Service metadata: labels: - app: MyApp + app.kubernetes.io/name: MyApp name: my-service spec: clusterIP: fd00::5118 @@ -172,7 +172,7 @@ spec: protocol: TCP targetPort: 80 selector: - app: MyApp + app.kubernetes.io/name: MyApp sessionAffinity: None type: ClusterIP status: @@ -187,7 +187,7 @@ Create the following Service that explicitly defines `PreferDualStack` in `.spec The `kubectl get svc` command will only show the primary IP in the `CLUSTER-IP` field. ```shell -kubectl get svc -l app=MyApp +kubectl get svc -l app.kubernetes.io/name=MyApp NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE my-service ClusterIP 10.0.216.242 80/TCP 5s @@ -197,15 +197,15 @@ my-service ClusterIP 10.0.216.242 80/TCP 5s Validate that the Service gets cluster IPs from the IPv4 and IPv6 address blocks using `kubectl describe`. You may then validate access to the service via the IPs and ports. ```shell -kubectl describe svc -l app=MyApp +kubectl describe svc -l app.kubernetes.io/name=MyApp ``` ``` Name: my-service Namespace: default -Labels: app=MyApp +Labels: app.kubernetes.io/name=MyApp Annotations: -Selector: app=MyApp +Selector: app.kubernetes.io/name=MyApp Type: ClusterIP IP Family Policy: PreferDualStack IP Families: IPv4,IPv6 @@ -220,14 +220,14 @@ Events: ### Create a dual-stack load balanced Service -If the cloud provider supports the provisioning of IPv6 enabled external load balancers, create the following Service with `PreferDualStack` in `.spec.ipFamilyPolicy`, `IPv6` as the first element of the `.spec.ipFamilies` array and the `type` field set to `LoadBalancer`. +If the cloud provider supports the provisioning of IPv6 enabled external load balancers, create the following Service with `PreferDualStack` in `.spec.ipFamilyPolicy`, `IPv6` as the first element of the `.spec.ipFamilies` array and the `type` field set to `LoadBalancer`. {{< codenew file="service/networking/dual-stack-prefer-ipv6-lb-svc.yaml" >}} Check the Service: ```shell -kubectl get svc -l app=MyApp +kubectl get svc -l app.kubernetes.io/name=MyApp ``` Validate that the Service receives a `CLUSTER-IP` address from the IPv6 address block along with an `EXTERNAL-IP`. You may then validate access to the service via the IP and port. diff --git a/content/en/docs/tasks/run-application/delete-stateful-set.md b/content/en/docs/tasks/run-application/delete-stateful-set.md index eff3aaee17..a867b73a61 100644 --- a/content/en/docs/tasks/run-application/delete-stateful-set.md +++ b/content/en/docs/tasks/run-application/delete-stateful-set.md @@ -50,10 +50,10 @@ For example: kubectl delete -f --cascade=orphan ``` -By passing `--cascade=orphan` to `kubectl delete`, the Pods managed by the StatefulSet are left behind even after the StatefulSet object itself is deleted. If the pods have a label `app=myapp`, you can then delete them as follows: +By passing `--cascade=orphan` to `kubectl delete`, the Pods managed by the StatefulSet are left behind even after the StatefulSet object itself is deleted. If the pods have a label `app.kubernetes.io/name=MyApp`, you can then delete them as follows: ```shell -kubectl delete pods -l app=myapp +kubectl delete pods -l app.kubernetes.io/name=MyApp ``` ### Persistent Volumes @@ -70,13 +70,13 @@ To delete everything in a StatefulSet, including the associated pods, you can ru ```shell grace=$(kubectl get pods --template '{{.spec.terminationGracePeriodSeconds}}') -kubectl delete statefulset -l app=myapp +kubectl delete statefulset -l app.kubernetes.io/name=MyApp sleep $grace -kubectl delete pvc -l app=myapp +kubectl delete pvc -l app.kubernetes.io/name=MyApp ``` -In the example above, the Pods have the label `app=myapp`; substitute your own label as appropriate. +In the example above, the Pods have the label `app.kubernetes.io/name=MyApp`; substitute your own label as appropriate. ### Force deletion of StatefulSet pods diff --git a/content/en/examples/service/networking/dual-stack-default-svc.yaml b/content/en/examples/service/networking/dual-stack-default-svc.yaml index 86eadd5478..a42c7d8a25 100644 --- a/content/en/examples/service/networking/dual-stack-default-svc.yaml +++ b/content/en/examples/service/networking/dual-stack-default-svc.yaml @@ -3,10 +3,10 @@ kind: Service metadata: name: my-service labels: - app: MyApp + app.kubernetes.io/name: MyApp spec: selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80 diff --git a/content/en/examples/service/networking/dual-stack-ipfamilies-ipv6.yaml b/content/en/examples/service/networking/dual-stack-ipfamilies-ipv6.yaml index 7c7239cae6..77949c883f 100644 --- a/content/en/examples/service/networking/dual-stack-ipfamilies-ipv6.yaml +++ b/content/en/examples/service/networking/dual-stack-ipfamilies-ipv6.yaml @@ -3,12 +3,12 @@ kind: Service metadata: name: my-service labels: - app: MyApp + app.kubernetes.io/name: MyApp spec: ipFamilies: - IPv6 selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80 diff --git a/content/en/examples/service/networking/dual-stack-ipv6-svc.yaml b/content/en/examples/service/networking/dual-stack-ipv6-svc.yaml index 2aa0725059..feb12f61a9 100644 --- a/content/en/examples/service/networking/dual-stack-ipv6-svc.yaml +++ b/content/en/examples/service/networking/dual-stack-ipv6-svc.yaml @@ -5,8 +5,8 @@ metadata: spec: ipFamily: IPv6 selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80 - targetPort: 9376 \ No newline at end of file + targetPort: 9376 diff --git a/content/en/examples/service/networking/dual-stack-prefer-ipv6-lb-svc.yaml b/content/en/examples/service/networking/dual-stack-prefer-ipv6-lb-svc.yaml index 0949a75428..5a4a99a45c 100644 --- a/content/en/examples/service/networking/dual-stack-prefer-ipv6-lb-svc.yaml +++ b/content/en/examples/service/networking/dual-stack-prefer-ipv6-lb-svc.yaml @@ -3,14 +3,14 @@ kind: Service metadata: name: my-service labels: - app: MyApp + app.kubernetes.io/name: MyApp spec: ipFamilyPolicy: PreferDualStack ipFamilies: - IPv6 type: LoadBalancer selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80 diff --git a/content/en/examples/service/networking/dual-stack-preferred-ipfamilies-svc.yaml b/content/en/examples/service/networking/dual-stack-preferred-ipfamilies-svc.yaml index c31acfec58..79a4f34a7f 100644 --- a/content/en/examples/service/networking/dual-stack-preferred-ipfamilies-svc.yaml +++ b/content/en/examples/service/networking/dual-stack-preferred-ipfamilies-svc.yaml @@ -3,14 +3,14 @@ kind: Service metadata: name: my-service labels: - app: MyApp + app.kubernetes.io/name: MyApp spec: ipFamilyPolicy: PreferDualStack ipFamilies: - IPv6 - IPv4 selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80 diff --git a/content/en/examples/service/networking/dual-stack-preferred-svc.yaml b/content/en/examples/service/networking/dual-stack-preferred-svc.yaml index 8fb5bfa3d3..66d42b9612 100644 --- a/content/en/examples/service/networking/dual-stack-preferred-svc.yaml +++ b/content/en/examples/service/networking/dual-stack-preferred-svc.yaml @@ -3,11 +3,11 @@ kind: Service metadata: name: my-service labels: - app: MyApp + app.kubernetes.io/name: MyApp spec: ipFamilyPolicy: PreferDualStack selector: - app: MyApp + app.kubernetes.io/name: MyApp ports: - protocol: TCP port: 80