kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Move Guide topic: Service. (#2891) 

* Move Guide topic: Service.

* Move Guide topic: External Load Balancer.

* Fix TOC.
reviewable/pr2894/r1
Steve Perry 2017-03-17 09:59:35 -07:00 committed by GitHub
parent e889494348
commit bf71f21a5b
4 changed files with 146 additions and 302 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
_data/tasks.yml
View File

@ -42,6 +42,7 @@ toc:
section:
- docs/tasks/access-application-cluster/port-forward-access-application-cluster.md
- docs/tasks/access-application-cluster/load-balance-access-application-cluster.md
- docs/tasks/access-application-cluster/create-external-load-balancer.md
- docs/tasks/access-application-cluster/configure-cloud-provider-firewall.md
- title: Monitoring, Logging, and Debugging

141
docs/tasks/access-application-cluster/create-external-load-balancer.md Normal file
View File

@ -0,0 +1,141 @@
---
title: Creating an External Load Balancer
---
* TOC
{:toc}
## Overview
When creating a service, you have the option of automatically creating a
cloud network load balancer. This provides an
externally-accessible IP address that sends traffic to the correct port on your
cluster nodes _provided your cluster runs in a supported environment and is configured with the correct cloud load balancer provider package_.
## External Load Balancer Providers
It is important to note that the datapath for this functionality is provided by a load balancer external to the Kubernetes cluster.
When the service type is set to `LoadBalancer`, Kubernetes provides functionality equivalent to type=`ClusterIP` to pods within the cluster and extends it by programming the (external to Kubernetes) load balancer with entries for the Kubernetes VMs. The Kubernetes service controller automates the creation of the external load balancer, health checks (if needed), firewall rules (if needed) and retrieves the external IP allocated by the cloud provider and populates it in the service object.
## Configuration file
To create an external load balancer, add the following line to your
[service configuration file](/docs/user-guide/services/operations/#service-configuration-file):
```json
"type": "LoadBalancer"
```
Your configuration file might look like:
```json
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": "example-service"
},
"spec": {
"ports": [{
"port": 8765,
"targetPort": 9376
}],
"selector": {
"app": "example"
},
"type": "LoadBalancer"
}
}
```
## Using kubectl
You can alternatively create the service with the `kubectl expose` command and
its `--type=LoadBalancer` flag:
```bash
$ kubectl expose rc example --port=8765 --target-port=9376 \
--name=example-service --type=LoadBalancer
```
This command creates a new service using the same selectors as the referenced
resource (in the case of the example above, a replication controller named
`example`.)
For more information, including optional flags, refer to the
[`kubectl expose` reference](/docs/user-guide/kubectl/kubectl_expose/).
## Finding your IP address
You can find the IP address created for your service by getting the service
information through `kubectl`:
```bash
$ kubectl describe services example-service
Name: example-service
Selector: app=example
Type: LoadBalancer
IP: 10.67.252.103
LoadBalancer Ingress: 123.45.678.9
Port: <unnamed> 80/TCP
NodePort: <unnamed> 32445/TCP
Endpoints: 10.64.0.4:80,10.64.1.5:80,10.64.2.4:80
Session Affinity: None
No events.
```
The IP address is listed next to `LoadBalancer Ingress`.
## Loss of client source IP for external traffic
Due to the implementation of this feature, the source IP for sessions as seen in the target container will *not be the original source IP* of the client. This is the default behavior as of Kubernetes v1.5. However, starting in v1.5, an optional beta feature has been added
that will preserve the client Source IP for GCE/GKE environments. This feature will be phased in for other cloud providers in subsequent releases.
## Annotation to modify the LoadBalancer behavior for preservation of Source IP
In 1.5, a Beta feature has been added that changes the behavior of the external LoadBalancer feature.
This feature can be activated by adding the beta annotation below to the metadata section of the Service Configuration file.
```json
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": "example-service",
"annotations": {
"service.beta.kubernetes.io/external-traffic": "OnlyLocal"
}
},
"spec": {
"ports": [{
"port": 8765,
"targetPort": 9376
}],
"selector": {
"app": "example"
},
"type": "LoadBalancer"
}
}
```
**Note that this feature is not currently implemented for all cloudproviders/environments.**
### Caveats and Limitations when preserving source IPs
GCE/AWS load balancers do not provide weights for their target pools. This was not an issue with the old LB
kube-proxy rules which would correctly balance across all endpoints.
With the new functionality, the external traffic will not be equally load balanced across pods, but rather
equally balanced at the node level (because GCE/AWS and other external LB implementations do not have the ability
for specifying the weight per node, they balance equally across all target nodes, disregarding the number of
pods on each node).
We can, however, state that for NumServicePods << NumNodes or NumServicePods >> NumNodes, a fairly close-to-equal
distribution will be seen, even without weights.
Once the external load balancers provide weights, this functionality can be added to the LB programming path.
*Future Work: No support for weights is provided for the 1.4 release, but may be added at a future date*
Internal pod to pod traffic should behave similar to ClusterIP services, with equal probability across all pods.

138
docs/user-guide/load-balancer.md
View File

@ -2,140 +2,6 @@
title: Creating an External Load Balancer
---
* TOC
{:toc}
{% include user-guide-content-moved.md %}
## Overview
When creating a service, you have the option of automatically creating a
cloud network load balancer. This provides an
externally-accessible IP address that sends traffic to the correct port on your
cluster nodes _provided your cluster runs in a supported environment and is configured with the correct cloud load balancer provider package_.
## External Load Balancer Providers
It is important to note that the datapath for this functionality is provided by a load balancer external to the Kubernetes cluster.
When the service type is set to `LoadBalancer`, Kubernetes provides functionality equivalent to type=`ClusterIP` to pods within the cluster and extends it by programming the (external to Kubernetes) load balancer with entries for the Kubernetes VMs. The Kubernetes service controller automates the creation of the external load balancer, health checks (if needed), firewall rules (if needed) and retrieves the external IP allocated by the cloud provider and populates it in the service object.
## Configuration file
To create an external load balancer, add the following line to your
[service configuration file](/docs/user-guide/services/operations/#service-configuration-file):
```json
"type": "LoadBalancer"
```
Your configuration file might look like:
```json
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": "example-service"
},
"spec": {
"ports": [{
"port": 8765,
"targetPort": 9376
}],
"selector": {
"app": "example"
},
"type": "LoadBalancer"
}
}
```
## Using kubectl
You can alternatively create the service with the `kubectl expose` command and
its `--type=LoadBalancer` flag:
```bash
$ kubectl expose rc example --port=8765 --target-port=9376 \
--name=example-service --type=LoadBalancer
```
This command creates a new service using the same selectors as the referenced
resource (in the case of the example above, a replication controller named
`example`.)
For more information, including optional flags, refer to the
[`kubectl expose` reference](/docs/user-guide/kubectl/kubectl_expose/).
## Finding your IP address
You can find the IP address created for your service by getting the service
information through `kubectl`:
```bash
$ kubectl describe services example-service
Name: example-service
Selector: app=example
Type: LoadBalancer
IP: 10.67.252.103
LoadBalancer Ingress: 123.45.678.9
Port: <unnamed> 80/TCP
NodePort: <unnamed> 32445/TCP
Endpoints: 10.64.0.4:80,10.64.1.5:80,10.64.2.4:80
Session Affinity: None
No events.
```
The IP address is listed next to `LoadBalancer Ingress`.
## Loss of client source IP for external traffic
Due to the implementation of this feature, the source IP for sessions as seen in the target container will *not be the original source IP* of the client. This is the default behavior as of Kubernetes v1.5. However, starting in v1.5, an optional beta feature has been added
that will preserve the client Source IP for GCE/GKE environments. This feature will be phased in for other cloud providers in subsequent releases.
## Annotation to modify the LoadBalancer behavior for preservation of Source IP
In 1.5, a Beta feature has been added that changes the behavior of the external LoadBalancer feature.
This feature can be activated by adding the beta annotation below to the metadata section of the Service Configuration file.
```json
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": "example-service",
"annotations": {
"service.beta.kubernetes.io/external-traffic": "OnlyLocal"
}
},
"spec": {
"ports": [{
"port": 8765,
"targetPort": 9376
}],
"selector": {
"app": "example"
},
"type": "LoadBalancer"
}
}
```
**Note that this feature is not currently implemented for all cloudproviders/environments.**
### Caveats and Limitations when preserving source IPs
GCE/AWS load balancers do not provide weights for their target pools. This was not an issue with the old LB
kube-proxy rules which would correctly balance across all endpoints.
With the new functionality, the external traffic will not be equally load balanced across pods, but rather
equally balanced at the node level (because GCE/AWS and other external LB implementations do not have the ability
for specifying the weight per node, they balance equally across all target nodes, disregarding the number of
pods on each node).
We can, however, state that for NumServicePods << NumNodes or NumServicePods >> NumNodes, a fairly close-to-equal
distribution will be seen, even without weights.
Once the external load balancers provide weights, this functionality can be added to the LB programming path.
*Future Work: No support for weights is provided for the 1.4 release, but may be added at a future date*
Internal pod to pod traffic should behave similar to ClusterIP services, with equal probability across all pods.
[Creating an External Load Balancer](/docs/tasks/access-application-cluster/create-external-load-balancer/)

168
docs/user-guide/services/operations.md
View File

@ -5,170 +5,6 @@ assignees:
title: Service Operations
---
* TOC
{:toc}
{% include user-guide-content-moved.md %}
Services map a port on each cluster node to ports on one or more pods.
The mapping uses a `selector` key:value pair in the service, and the
`labels` property of pods. Any pods whose labels match the service selector
are made accessible through the service's port.
For more information, see the
[Services Overview](/docs/user-guide/services/).
## Create a service
Services are created by passing a configuration file to the `kubectl create`
command:
```shell
$ kubectl create -f FILE
```
Where:
* `-f FILE` or `--filename FILE` is a relative path to a
[service configuration file](#service-configuration-file) in either JSON
or YAML format.
A successful service create request returns the service name. You can use
a [sample file](#sample_files) below to try a create request.
### Service configuration file
When creating a service, you must point to a service configuration file as the
value of the `-f` flag. The configuration file can be formatted as
YAML or as JSON, and supports the following fields:
```json
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": string
},
"spec": {
"ports": [{
"port": int,
"targetPort": int
}],
"selector": {
string: string
},
"type": "LoadBalancer",
"loadBalancerSourceRanges": [
"10.180.0.0/16",
"10.245.0.0/24"
]
}
}
```
Required fields are:
* `kind`: Always `Service`.
* `apiVersion`: Currently `v1`.
* `metadata`: Contains:
* `name`: The name to give to this service.
* `spec`: Contains:
* `ports`: The ports to map. `port` is the service port to expose on the
cluster IP. `targetPort` is the port to target on the pods that are part
of this service.
* `selector`: The label key:value pair that defines the pods to
target.
* `type`: Optional. If the type is `LoadBalancer`, sets up a [network load balancer](/docs/user-guide/load-balancer/)
for your service. This provides an externally-accessible IP address that
sends traffic to the correct port on your cluster nodes.
* `loadBalancerSourceRanges:`: Optional. Must use with `LoadBalancer` type.
If specified and supported by the cloud provider, this will restrict traffic
such that the load balancer will be accessible only to clients from the specified IP ranges.
This field will be ignored if the cloud-provider does not support the feature.
For the full `service` schema see the
[Kubernetes api reference](/docs/api-reference/v1/definitions/#_v1_service).
### Sample files
The following service configuration files assume that you have a set of pods
that expose port 9376 and carry the label `app=example`.
Both files create a new service named `myapp` which resolves to TCP port 9376
on any pod with the `app=example` label.
The difference in the files is in how the service is accessed. The first file
does not create an external load balancer; the service can be accessed through
port 8765 on any of the nodes' IP addresses.
{% capture tabspec %}servicesample
JSON,json,service-sample.json,/docs/user-guide/services/service-sample.json
YAML,yaml,service-sample.yaml,/docs/user-guide/services/service-sample.yaml{% endcapture %}
{% include tabs.html %}
The second file uses
[network load balancing](/docs/user-guide/load-balancer/) to create a
single IP address that spreads traffic to all of the nodes in
your cluster. This option is specified with the
`"type": "LoadBalancer"` property.
{% capture tabspec %}loadbalancesample
JSON,json,load-balancer-sample.json,/docs/user-guide/services/load-balancer-sample.json
YAML,yaml,load-balancer-sample.yaml,/docs/user-guide/services/load-balancer-sample.yaml{% endcapture %}
{% include tabs.html %}
To access the service, a client connects to the external IP address, which
forwards to port 8765 on a node in the cluster, which in turn accesses
port 9376 on the pod. See the
[Service configuration file](#service-configuration-file) section of this doc
for directions on finding the external IP address.
## View a service
To list all services on a cluster, use the
`kubectl get` command:
```shell
$ kubectl get services
```
A successful get request returns all services that exist on the specified
cluster:
```shell
NAME LABELS SELECTOR IP PORT
myapp <none> app=MyApp 10.123.255.83 8765/TCP
```
To return information about a specific service, use the
`kubectl describe` command:
```shell
$ kubectl describe service NAME
```
Details about the specific service are returned:
```conf
Name: myapp
Labels: <none>
Selector: app=MyApp
IP: 10.123.255.83
Port: <unnamed> 8765/TCP
NodePort: <unnamed> 31474/TCP
Endpoints: <none>
Session Affinity: None
No events.
```
To return information about a service when event information is not required,
substitute `get` for `describe`.
## Delete a service
To delete a service, use the `kubectl delete` command:
```shell
$ kubectl delete service NAME
```
A successful delete request returns the deleted service's name.
[Connecting a Front End to a Back End Using a Service](/docs/tutorials/connecting-apps/connecting-frontend-backend/)