Skip to content

Commit

Permalink
Fix some nits in the service concept page
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@tengqm
tengqm committed Oct 16, 2023
1 parent 52ecdb6 commit 6ed6bed
Showing 1 changed file with 50 additions and 62 deletions.
112 changes: 50 additions & 62 deletions content/en/docs/concepts/services-networking/service.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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 >}}
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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}

Expand Down Expand Up @@ -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
```

Expand All @@ -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`)
Expand All @@ -556,7 +555,8 @@ This means that kube-proxy should consider all available network interfaces for
{{< note >}}
This Service is visible as `<NodeIP>: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, `<NodeIP>` would be a filtered node IP address (or possibly IP addresses).
in the kube-proxy configuration file is set, `<NodeIP>` would be a filtered
node IP address (or possibly IP addresses).
{{< /note >}}

### `type: LoadBalancer` {#loadbalancer}
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -1015,14 +1000,17 @@ 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.
* Read about [Gateway](https://gateway-api.sigs.k8s.io/), an extension to
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/)
Expand Down

0 comments on commit 6ed6bed

Please sign in to comment.