Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update ESIPP documentation to reflect new fields #4093

Merged
merged 1 commit into from
Jun 27, 2017
Merged

Update ESIPP documentation to reflect new fields #4093

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 49 additions & 14 deletions docs/tasks/access-application-cluster/create-external-load-balancer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,9 @@ information through `kubectl`:
```bash
kubectl describe services example-service
```

which should produce output like this:

```bash
Name: example-service
Selector: app=example
Expand All @@ -97,20 +99,36 @@ which should produce output like this:

The IP address is listed next to `LoadBalancer Ingress`.

## 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.
## Preserving the client source IP

Due to the implementation of this feature, the source IP seen in the target
container will *not be the original source IP* of the client. To enable
preservation of the client IP, the following fields can be configured in the
service spec (supported in GCE/GKE environments):

* `service.spec.externalTrafficPolicy` - denotes if this Service desires to route
external traffic to node-local or cluster-wide endpoints. There are two available
options: "Cluster" (default) and "Local". "Cluster" obscures the client source
IP and may cause a second hop to another node, but should have good overall
load-spreading. "Local" preserves the client source IP and avoids a second hop
for LoadBalancer and NodePort type services, but risks potentially imbalanced
traffic spreading.
* `service.spec.healthCheckNodePort` - specifies the healthcheck nodePort
(numeric port number) for the service. If not specified, healthCheckNodePort is
created by the service API backend with the allocated nodePort. It will use the
user-specified nodePort value if specified by the client. It only has an
effect when type is set to "LoadBalancer" and externalTrafficPolicy is set
to "Local".

This feature can be activated by setting `externalTrafficPolicy` to "Local" in the
Service Configuration file.

```json
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": "example-service",
"annotations": {
"service.beta.kubernetes.io/external-traffic": "OnlyLocal"
}
},
"spec": {
"ports": [{
Expand All @@ -120,11 +138,33 @@ This feature can be activated by adding the beta annotation below to the metadat
"selector": {
"app": "example"
},
"type": "LoadBalancer"
"type": "LoadBalancer",
"externalTrafficPolicy": "Local"
}
}
```

### Feature availability

| k8s version | Feature support |
| :---------: |:-----------:|
| 1.7+ | Supports the full API fields |
| 1.5 - 1.6 | Supports Beta Annotations |
| <1.5 | Unsupported |

Below you could find the deprecated Beta annotations used to enable this feature
prior to its stable version. Newer Kubernetes versions may stop supporting these
after v1.7. Please update existing applications to use the fields directly.

* `service.beta.kubernetes.io/external-traffic` annotation <-> `service.spec.externalTrafficPolicy` field
* `service.beta.kubernetes.io/healthcheck-nodeport` annotation <-> `service.spec.healthCheckNodePort` field

`service.beta.kubernetes.io/external-traffic` annotation has a different set of values
compared to the `service.spec.externalTrafficPolicy` field. The values match as follows:

* "OnlyLocal" for annotation <-> "Local" for field
* "Global" for annotation <-> "Cluster" for field

**Note that this feature is not currently implemented for all cloudproviders/environments.**


Expand All @@ -138,11 +178,6 @@ It is important to note that the datapath for this functionality is provided by

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.

## 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.

## 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
Expand All @@ -163,4 +198,4 @@ Internal pod to pod traffic should behave similar to ClusterIP services, with eq

{% endcapture %}

{% include templates/task.md %}
{% include templates/task.md %}