Skip to content

Commit 6ed6bed

Browse files
committed
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.
1 parent 52ecdb6 commit 6ed6bed

File tree

1 file changed

+50
-62
lines changed
  • content/en/docs/concepts/services-networking

1 file changed

+50
-62
lines changed

content/en/docs/concepts/services-networking/service.md

Lines changed: 50 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,6 @@ spec:
175175
targetPort: http-web-svc
176176
```
177177

178-
179178
This works even if there is a mixture of Pods in the Service using a single
180179
configured name, with the same network protocol available via different
181180
port numbers. This offers a lot of flexibility for deploying and evolving
@@ -269,7 +268,8 @@ as a destination.
269268
{{< /note >}}
270269

271270
For an EndpointSlice that you create yourself, or in your own code,
272-
you should also pick a value to use for the [`endpointslice.kubernetes.io/managed-by`](/docs/reference/labels-annotations-taints/#endpointslicekubernetesiomanaged-by) label.
271+
you should also pick a value to use for the label
272+
[`endpointslice.kubernetes.io/managed-by`](/docs/reference/labels-annotations-taints/#endpointslicekubernetesiomanaged-by).
273273
If you create your own controller code to manage EndpointSlices, consider using a
274274
value similar to `"my-domain.example/name-of-controller"`. If you are using a third
275275
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.
283283
#### Accessing a Service without a selector {#service-no-selector-access}
284284

285285
Accessing a Service without a selector works the same as if it had a selector.
286-
In the [example](#services-without-selectors) for a Service without a selector, traffic is routed to one of the two endpoints defined in
286+
In the [example](#services-without-selectors) for a Service without a selector,
287+
traffic is routed to one of the two endpoints defined in
287288
the EndpointSlice manifest: a TCP connection to 10.1.2.3 or 10.4.5.6, on port 9376.
288289

289290
{{< note >}}
@@ -334,8 +335,7 @@ affects the legacy Endpoints API.
334335

335336
In that case, Kubernetes selects at most 1000 possible backend endpoints to store
336337
into the Endpoints object, and sets an
337-
{{< glossary_tooltip text="annotation" term_id="annotation" >}} on the
338-
Endpoints:
338+
{{< glossary_tooltip text="annotation" term_id="annotation" >}} on the Endpoints:
339339
[`endpoints.kubernetes.io/over-capacity: truncated`](/docs/reference/labels-annotations-taints/#endpoints-kubernetes-io-over-capacity).
340340
The control plane also removes that annotation if the number of backend Pods drops below 1000.
341341

@@ -349,7 +349,8 @@ The same API limit means that you cannot manually update an Endpoints to have mo
349349
{{< feature-state for_k8s_version="v1.20" state="stable" >}}
350350

351351
The `appProtocol` field provides a way to specify an application protocol for
352-
each Service port. This is used as a hint for implementations to offer richer behavior for protocols that they understand.
352+
each Service port. This is used as a hint for implementations to offer
353+
richer behavior for protocols that they understand.
353354
The value of this field is mirrored by the corresponding
354355
Endpoints and EndpointSlice objects.
355356

@@ -365,8 +366,6 @@ This field follows standard Kubernetes label syntax. Valid values are one of:
365366
|----------|-------------|
366367
| `kubernetes.io/h2c` | HTTP/2 over cleartext as described in [RFC 7540](https://www.rfc-editor.org/rfc/rfc7540) |
367368

368-
369-
370369
### Multi-port Services
371370

372371
For some Services, you need to expose more than one port.
@@ -402,7 +401,6 @@ also start and end with an alphanumeric character.
402401
For example, the names `123-abc` and `web` are valid, but `123_abc` and `-web` are not.
403402
{{< /note >}}
404403

405-
406404
## Service type {#publishing-services-service-types}
407405

408406
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:
417415
: Exposes the Service on a cluster-internal IP. Choosing this value
418416
makes the Service only reachable from within the cluster. This is the
419417
default that is used if you don't explicitly specify a `type` for a Service.
420-
You can expose the Service to the public internet using an [Ingress](/docs/concepts/services-networking/ingress/) or a
418+
You can expose the Service to the public internet using an
419+
[Ingress](/docs/concepts/services-networking/ingress/) or a
421420
[Gateway](https://gateway-api.sigs.k8s.io/).
422421

423422
[`NodePort`](#type-nodeport)
@@ -439,8 +438,7 @@ The available `type` values and their behaviors are:
439438
The `type` field in the Service API is designed as nested functionality - each level
440439
adds to the previous. However there is an exception to this nested design. You can
441440
define a `LoadBalancer` Service by
442-
[disabling the load balancer `NodePort` allocation.](/docs/concepts/services-networking/service/#load-balancer-nodeport-allocation)
443-
441+
[disabling the load balancer `NodePort` allocation](/docs/concepts/services-networking/service/#load-balancer-nodeport-allocation).
444442

445443
### `type: ClusterIP` {#type-clusterip}
446444

@@ -510,11 +508,13 @@ spec:
510508
selector:
511509
app.kubernetes.io/name: MyApp
512510
ports:
513-
# By default and for convenience, the `targetPort` is set to the same value as the `port` field.
514511
- port: 80
512+
# By default and for convenience, the `targetPort` is set to
513+
# the same value as the `port` field.
515514
targetPort: 80
516515
# Optional field
517-
# By default and for convenience, the Kubernetes control plane will allocate a port from a range (default: 30000-32767)
516+
# By default and for convenience, the Kubernetes control plane
517+
# will allocate a port from a range (default: 30000-32767)
518518
nodePort: 30007
519519
```
520520
@@ -541,8 +541,7 @@ control plane).
541541

542542
If you want to specify particular IP address(es) to proxy the port, you can set the
543543
`--nodeport-addresses` flag for kube-proxy or the equivalent `nodePortAddresses`
544-
field of the
545-
[kube-proxy configuration file](/docs/reference/config-api/kube-proxy-config.v1alpha1/)
544+
field of the [kube-proxy configuration file](/docs/reference/config-api/kube-proxy-config.v1alpha1/)
546545
to particular IP block(s).
547546

548547
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
556555
{{< note >}}
557556
This Service is visible as `<NodeIP>:spec.ports[*].nodePort` and `.spec.clusterIP:spec.ports[*].port`.
558557
If the `--nodeport-addresses` flag for kube-proxy or the equivalent field
559-
in the kube-proxy configuration file is set, `<NodeIP>` would be a filtered node IP address (or possibly IP addresses).
558+
in the kube-proxy configuration file is set, `<NodeIP>` would be a filtered
559+
node IP address (or possibly IP addresses).
560560
{{< /note >}}
561561

562562
### `type: LoadBalancer` {#loadbalancer}
@@ -610,7 +610,8 @@ set is ignored.
610610
{{< note >}}
611611
The`.spec.loadBalancerIP` field for a Service was deprecated in Kubernetes v1.24.
612612

613-
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.
613+
This field was under-specified and its meaning varies across implementations.
614+
It also cannot support dual-stack networking. This field may be removed in a future API version.
614615

615616
If you're integrating with a provider that supports specifying the load balancer IP address(es)
616617
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:
684685
{{% tab name="Default" %}}
685686
Select one of the tabs.
686687
{{% /tab %}}
688+
687689
{{% tab name="GCP" %}}
688690

689691
```yaml
690-
[...]
691692
metadata:
692-
name: my-service
693-
annotations:
694-
networking.gke.io/load-balancer-type: "Internal"
695-
[...]
693+
name: my-service
694+
annotations:
695+
networking.gke.io/load-balancer-type: "Internal"
696696
```
697-
698697
{{% /tab %}}
699698
{{% tab name="AWS" %}}
700699

701700
```yaml
702-
[...]
703701
metadata:
704702
name: my-service
705703
annotations:
706704
service.beta.kubernetes.io/aws-load-balancer-internal: "true"
707-
[...]
708705
```
709706

710707
{{% /tab %}}
711708
{{% tab name="Azure" %}}
712709

713710
```yaml
714-
[...]
715711
metadata:
716-
name: my-service
717-
annotations:
718-
service.beta.kubernetes.io/azure-load-balancer-internal: "true"
719-
[...]
712+
name: my-service
713+
annotations:
714+
service.beta.kubernetes.io/azure-load-balancer-internal: "true"
720715
```
721716

722717
{{% /tab %}}
723718
{{% tab name="IBM Cloud" %}}
724719

725720
```yaml
726-
[...]
727721
metadata:
728-
name: my-service
729-
annotations:
730-
service.kubernetes.io/ibm-load-balancer-cloud-provider-ip-type: "private"
731-
[...]
722+
name: my-service
723+
annotations:
724+
service.kubernetes.io/ibm-load-balancer-cloud-provider-ip-type: "private"
732725
```
733726

734727
{{% /tab %}}
735728
{{% tab name="OpenStack" %}}
736729

737730
```yaml
738-
[...]
739731
metadata:
740-
name: my-service
741-
annotations:
742-
service.beta.kubernetes.io/openstack-internal-load-balancer: "true"
743-
[...]
732+
name: my-service
733+
annotations:
734+
service.beta.kubernetes.io/openstack-internal-load-balancer: "true"
744735
```
745736

746737
{{% /tab %}}
747738
{{% tab name="Baidu Cloud" %}}
748739

749740
```yaml
750-
[...]
751741
metadata:
752-
name: my-service
753-
annotations:
754-
service.beta.kubernetes.io/cce-load-balancer-internal-vpc: "true"
755-
[...]
742+
name: my-service
743+
annotations:
744+
service.beta.kubernetes.io/cce-load-balancer-internal-vpc: "true"
756745
```
757746

758747
{{% /tab %}}
759748
{{% tab name="Tencent Cloud" %}}
760749

761750
```yaml
762-
[...]
763751
metadata:
764752
annotations:
765753
service.kubernetes.io/qcloud-loadbalancer-internal-subnetid: subnet-xxxxx
766-
[...]
767754
```
768755

769756
{{% /tab %}}
770757
{{% tab name="Alibaba Cloud" %}}
771758

772759
```yaml
773-
[...]
774760
metadata:
775761
annotations:
776762
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: "intranet"
777-
[...]
778763
```
779764

780765
{{% /tab %}}
781766
{{% tab name="OCI" %}}
782767

783768
```yaml
784-
[...]
785769
metadata:
786-
name: my-service
787-
annotations:
788-
service.beta.kubernetes.io/oci-load-balancer-internal: true
789-
[...]
770+
name: my-service
771+
annotations:
772+
service.beta.kubernetes.io/oci-load-balancer-internal: true
790773
```
791774
{{% /tab %}}
792775
{{< /tabs >}}
793776

794777
### `type: ExternalName` {#externalname}
795778

796-
797-
798779
Services of type ExternalName map a Service to a DNS name, not to a typical selector such as
799780
`my-service` or `cassandra`. You specify these Services with the `spec.externalName` parameter.
800781

@@ -813,11 +794,14 @@ spec:
813794
```
814795

815796
{{< note >}}
816-
A Service of `type: ExternalName` accepts an IPv4 address string, but treats that string as a DNS name comprised of digits,
817-
not as an IP address (the internet does not however allow such names in DNS). Services with external names that resemble IPv4
797+
A Service of `type: ExternalName` accepts an IPv4 address string,
798+
but treats that string as a DNS name comprised of digits,
799+
not as an IP address (the internet does not however allow such names in DNS).
800+
Services with external names that resemble IPv4
818801
addresses are not resolved by DNS servers.
819802

820-
If you want to map a Service directly to a specific IP address, consider using [headless Services](#headless-services).
803+
If you want to map a Service directly to a specific IP address, consider using
804+
[headless Services](#headless-services).
821805
{{< /note >}}
822806

823807
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.
883867
When a Pod is run on a Node, the kubelet adds a set of environment variables
884868
for each active Service. It adds `{SVCNAME}_SERVICE_HOST` and `{SVCNAME}_SERVICE_PORT` variables,
885869
where the Service name is upper-cased and dashes are converted to underscores.
886-
It also supports variables (see [makeLinkVariables](https://github.com/kubernetes/kubernetes/blob/dd2d12f6dc0e654c15d5db57a5f9f6ba61192726/pkg/kubelet/envvars/envvars.go#L72))
870+
It also supports variables
871+
(see [makeLinkVariables](https://github.com/kubernetes/kubernetes/blob/dd2d12f6dc0e654c15d5db57a5f9f6ba61192726/pkg/kubelet/envvars/envvars.go#L72))
887872
that are compatible with Docker Engine's
888873
"_[legacy container links](https://docs.docker.com/network/links/)_" feature.
889874

@@ -1015,14 +1000,17 @@ about the [Service API object](/docs/reference/generated/kubernetes-api/{{< para
10151000
## {{% heading "whatsnext" %}}
10161001

10171002
Learn more about Services and how they fit into Kubernetes:
1018-
* Follow the [Connecting Applications with Services](/docs/tutorials/services/connect-applications-service/) tutorial.
1003+
1004+
* Follow the [Connecting Applications with Services](/docs/tutorials/services/connect-applications-service/)
1005+
tutorial.
10191006
* Read about [Ingress](/docs/concepts/services-networking/ingress/), which
10201007
exposes HTTP and HTTPS routes from outside the cluster to Services within
10211008
your cluster.
10221009
* Read about [Gateway](https://gateway-api.sigs.k8s.io/), an extension to
10231010
Kubernetes that provides more flexibility than Ingress.
10241011

10251012
For more context, read the following:
1013+
10261014
* [Virtual IPs and Service Proxies](/docs/reference/networking/virtual-ips/)
10271015
* [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/)
10281016
* [Service API reference](/docs/reference/kubernetes-api/service-resources/service-v1/)

0 commit comments

Comments
 (0)