From 6ed6bedd936215bc6782644c8c49c8bdc39437b9 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Fri, 13 Oct 2023 21:12:14 +0800 Subject: [PATCH] Fix some nits in the service concept page This PR fixes some nits in the Service concepts page. - There are duplicated anchors in the page. For other pages pointing to those anchors, the results are unpredictable. - There are long lines that are not manually wrapped properly. - The `[...]` lines in sample YAML snippets are unnecessary. Their side effects are making the snippets invalid YAMLs. We can safely drop them without causing any confusion. --- .../concepts/services-networking/service.md | 112 ++++++++---------- 1 file changed, 50 insertions(+), 62 deletions(-) diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index b9d809f8bfdca..70f148e3d2d6e 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -175,7 +175,6 @@ spec: targetPort: http-web-svc ``` - 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 @@ -269,7 +268,8 @@ as a destination. {{< /note >}} For an EndpointSlice that you create yourself, or in your own code, -you should also pick a value to use for the [`endpointslice.kubernetes.io/managed-by`](/docs/reference/labels-annotations-taints/#endpointslicekubernetesiomanaged-by) label. +you should also pick a value to use for the label +[`endpointslice.kubernetes.io/managed-by`](/docs/reference/labels-annotations-taints/#endpointslicekubernetesiomanaged-by). If you create your own controller code to manage EndpointSlices, consider using a value similar to `"my-domain.example/name-of-controller"`. If you are using a third party tool, use the name of the tool in all-lowercase and change spaces and other @@ -283,7 +283,8 @@ managed by Kubernetes' own control plane. #### Accessing a Service without a selector {#service-no-selector-access} Accessing a Service without a selector works the same as if it had a selector. -In the [example](#services-without-selectors) for a Service without a selector, traffic is routed to one of the two endpoints defined in +In the [example](#services-without-selectors) for a Service without a selector, +traffic is routed to one of the two endpoints defined in the EndpointSlice manifest: a TCP connection to 10.1.2.3 or 10.4.5.6, on port 9376. {{< note >}} @@ -334,8 +335,7 @@ affects the legacy Endpoints API. In that case, Kubernetes selects at most 1000 possible backend endpoints to store into the Endpoints object, and sets an -{{< glossary_tooltip text="annotation" term_id="annotation" >}} on the -Endpoints: +{{< glossary_tooltip text="annotation" term_id="annotation" >}} on the Endpoints: [`endpoints.kubernetes.io/over-capacity: truncated`](/docs/reference/labels-annotations-taints/#endpoints-kubernetes-io-over-capacity). The control plane also removes that annotation if the number of backend Pods drops below 1000. @@ -349,7 +349,8 @@ The same API limit means that you cannot manually update an Endpoints to have mo {{< feature-state for_k8s_version="v1.20" state="stable" >}} The `appProtocol` field provides a way to specify an application protocol for -each Service port. This is used as a hint for implementations to offer richer behavior for protocols that they understand. +each Service port. This is used as a hint for implementations to offer +richer behavior for protocols that they understand. The value of this field is mirrored by the corresponding Endpoints and EndpointSlice objects. @@ -365,8 +366,6 @@ This field follows standard Kubernetes label syntax. Valid values are one of: |----------|-------------| | `kubernetes.io/h2c` | HTTP/2 over cleartext as described in [RFC 7540](https://www.rfc-editor.org/rfc/rfc7540) | - - ### Multi-port Services For some Services, you need to expose more than one port. @@ -402,7 +401,6 @@ also start and end with an alphanumeric character. For example, the names `123-abc` and `web` are valid, but `123_abc` and `-web` are not. {{< /note >}} - ## Service type {#publishing-services-service-types} For some parts of your application (for example, frontends) you may want to expose a @@ -417,7 +415,8 @@ The available `type` values and their behaviors are: : Exposes the Service on a cluster-internal IP. Choosing this value makes the Service only reachable from within the cluster. This is the default that is used if you don't explicitly specify a `type` for a Service. - You can expose the Service to the public internet using an [Ingress](/docs/concepts/services-networking/ingress/) or a + You can expose the Service to the public internet using an + [Ingress](/docs/concepts/services-networking/ingress/) or a [Gateway](https://gateway-api.sigs.k8s.io/). [`NodePort`](#type-nodeport) @@ -439,8 +438,7 @@ The available `type` values and their behaviors are: The `type` field in the Service API is designed as nested functionality - each level adds to the previous. However there is an exception to this nested design. You can define a `LoadBalancer` Service by -[disabling the load balancer `NodePort` allocation.](/docs/concepts/services-networking/service/#load-balancer-nodeport-allocation) - +[disabling the load balancer `NodePort` allocation](/docs/concepts/services-networking/service/#load-balancer-nodeport-allocation). ### `type: ClusterIP` {#type-clusterip} @@ -510,11 +508,13 @@ spec: selector: 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 + # By default and for convenience, the `targetPort` is set to + # the same value as the `port` field. targetPort: 80 # Optional field - # By default and for convenience, the Kubernetes control plane will allocate a port from a range (default: 30000-32767) + # By default and for convenience, the Kubernetes control plane + # will allocate a port from a range (default: 30000-32767) nodePort: 30007 ``` @@ -541,8 +541,7 @@ control plane). If you want to specify particular IP address(es) to proxy the port, you can set the `--nodeport-addresses` flag for kube-proxy or the equivalent `nodePortAddresses` -field of the -[kube-proxy configuration file](/docs/reference/config-api/kube-proxy-config.v1alpha1/) +field of the [kube-proxy configuration file](/docs/reference/config-api/kube-proxy-config.v1alpha1/) to particular IP block(s). This flag takes a comma-delimited list of IP blocks (e.g. `10.0.0.0/8`, `192.0.2.0/25`) @@ -556,7 +555,8 @@ This means that kube-proxy should consider all available network interfaces for {{< note >}} This Service is visible as `:spec.ports[*].nodePort` and `.spec.clusterIP:spec.ports[*].port`. If the `--nodeport-addresses` flag for kube-proxy or the equivalent field -in the kube-proxy configuration file is set, `` would be a filtered node IP address (or possibly IP addresses). +in the kube-proxy configuration file is set, `` would be a filtered +node IP address (or possibly IP addresses). {{< /note >}} ### `type: LoadBalancer` {#loadbalancer} @@ -610,7 +610,8 @@ set is ignored. {{< note >}} The`.spec.loadBalancerIP` field for a Service was deprecated in Kubernetes v1.24. -This field was under-specified and its meaning varies across implementations. It also cannot support dual-stack networking. This field may be removed in a future API version. +This field was under-specified and its meaning varies across implementations. +It also cannot support dual-stack networking. This field may be removed in a future API version. If you're integrating with a provider that supports specifying the load balancer IP address(es) for a Service via a (provider specific) annotation, you should switch to doing that. @@ -684,117 +685,97 @@ depending on the cloud service provider you're using: {{% tab name="Default" %}} Select one of the tabs. {{% /tab %}} + {{% tab name="GCP" %}} ```yaml -[...] metadata: - name: my-service - annotations: - networking.gke.io/load-balancer-type: "Internal" -[...] + name: my-service + annotations: + networking.gke.io/load-balancer-type: "Internal" ``` - {{% /tab %}} {{% tab name="AWS" %}} ```yaml -[...] metadata: name: my-service annotations: service.beta.kubernetes.io/aws-load-balancer-internal: "true" -[...] ``` {{% /tab %}} {{% tab name="Azure" %}} ```yaml -[...] metadata: - name: my-service - annotations: - service.beta.kubernetes.io/azure-load-balancer-internal: "true" -[...] + name: my-service + annotations: + service.beta.kubernetes.io/azure-load-balancer-internal: "true" ``` {{% /tab %}} {{% tab name="IBM Cloud" %}} ```yaml -[...] metadata: - name: my-service - annotations: - service.kubernetes.io/ibm-load-balancer-cloud-provider-ip-type: "private" -[...] + name: my-service + annotations: + service.kubernetes.io/ibm-load-balancer-cloud-provider-ip-type: "private" ``` {{% /tab %}} {{% tab name="OpenStack" %}} ```yaml -[...] metadata: - name: my-service - annotations: - service.beta.kubernetes.io/openstack-internal-load-balancer: "true" -[...] + name: my-service + annotations: + service.beta.kubernetes.io/openstack-internal-load-balancer: "true" ``` {{% /tab %}} {{% tab name="Baidu Cloud" %}} ```yaml -[...] metadata: - name: my-service - annotations: - service.beta.kubernetes.io/cce-load-balancer-internal-vpc: "true" -[...] + name: my-service + annotations: + service.beta.kubernetes.io/cce-load-balancer-internal-vpc: "true" ``` {{% /tab %}} {{% tab name="Tencent Cloud" %}} ```yaml -[...] metadata: annotations: service.kubernetes.io/qcloud-loadbalancer-internal-subnetid: subnet-xxxxx -[...] ``` {{% /tab %}} {{% tab name="Alibaba Cloud" %}} ```yaml -[...] metadata: annotations: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: "intranet" -[...] ``` {{% /tab %}} {{% tab name="OCI" %}} ```yaml -[...] metadata: - name: my-service - annotations: - service.beta.kubernetes.io/oci-load-balancer-internal: true -[...] + name: my-service + annotations: + service.beta.kubernetes.io/oci-load-balancer-internal: true ``` {{% /tab %}} {{< /tabs >}} ### `type: ExternalName` {#externalname} - - Services of type ExternalName map a Service to a DNS name, not to a typical selector such as `my-service` or `cassandra`. You specify these Services with the `spec.externalName` parameter. @@ -813,11 +794,14 @@ spec: ``` {{< note >}} -A Service of `type: ExternalName` accepts an IPv4 address string, but treats that string as a DNS name comprised of digits, -not as an IP address (the internet does not however allow such names in DNS). Services with external names that resemble IPv4 +A Service of `type: ExternalName` accepts an IPv4 address string, +but treats that string as a DNS name comprised of digits, +not as an IP address (the internet does not however allow such names in DNS). +Services with external names that resemble IPv4 addresses are not resolved by DNS servers. -If you want to map a Service directly to a specific IP address, consider using [headless Services](#headless-services). +If you want to map a Service directly to a specific IP address, consider using +[headless Services](#headless-services). {{< /note >}} When looking up the host `my-service.prod.svc.cluster.local`, the cluster DNS Service @@ -883,7 +867,8 @@ finding a Service: environment variables and DNS. When a Pod is run on a Node, the kubelet adds a set of environment variables for each active Service. It adds `{SVCNAME}_SERVICE_HOST` and `{SVCNAME}_SERVICE_PORT` variables, where the Service name is upper-cased and dashes are converted to underscores. -It also supports variables (see [makeLinkVariables](https://github.com/kubernetes/kubernetes/blob/dd2d12f6dc0e654c15d5db57a5f9f6ba61192726/pkg/kubelet/envvars/envvars.go#L72)) +It also supports variables +(see [makeLinkVariables](https://github.com/kubernetes/kubernetes/blob/dd2d12f6dc0e654c15d5db57a5f9f6ba61192726/pkg/kubelet/envvars/envvars.go#L72)) that are compatible with Docker Engine's "_[legacy container links](https://docs.docker.com/network/links/)_" feature. @@ -1015,7 +1000,9 @@ about the [Service API object](/docs/reference/generated/kubernetes-api/{{< para ## {{% heading "whatsnext" %}} Learn more about Services and how they fit into Kubernetes: -* Follow the [Connecting Applications with Services](/docs/tutorials/services/connect-applications-service/) tutorial. + +* Follow the [Connecting Applications with Services](/docs/tutorials/services/connect-applications-service/) + tutorial. * Read about [Ingress](/docs/concepts/services-networking/ingress/), which exposes HTTP and HTTPS routes from outside the cluster to Services within your cluster. @@ -1023,6 +1010,7 @@ Learn more about Services and how they fit into Kubernetes: Kubernetes that provides more flexibility than Ingress. For more context, read the following: + * [Virtual IPs and Service Proxies](/docs/reference/networking/virtual-ips/) * [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/) * [Service API reference](/docs/reference/kubernetes-api/service-resources/service-v1/)