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

Update ingress.md

pull/3803/head
paulbattagliag 2017-05-14 16:58:39 -07:00 committed by Andrew Chen
parent 0b26becd2b
commit 0acc7f3996
1 changed files with 73 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
docs/tasks/administer-federation/ingress.md
View File

@ -4,15 +4,14 @@ redirect_from:
- "/docs/user-guide/federation/federated-ingress/" - "/docs/user-guide/federation/federated-ingress/"
- "/docs/user-guide/federation/federated-ingress.html" - "/docs/user-guide/federation/federated-ingress.html"
--- ---
{% capture overview %}
This guide explains how to use Kubernetes Federated Ingress to deploy This page explains how to use Kubernetes Federated Ingress to deploy
a common HTTP(S) virtual IP load balancer across a federated service running in a common HTTP(S) virtual IP load balancer across a federated service running in
multiple Kubernetes clusters. As of v1.4, clusters hosted in Google multiple Kubernetes clusters. As of v1.4, clusters hosted in Google
Cloud (both GKE and GCE, or both) are supported. This makes it Cloud (both GKE and GCE, or both) are supported. This makes it
easy to deploy a service that reliably serves HTTP(S) traffic easy to deploy a service that reliably serves HTTP(S) traffic
originating from web clients around the globe on a single, static IP originating from web clients around the globe on a single, static IP
address. Low address. Low network latency, high fault tolerance and easy administration are
network latency, high fault tolerance and easy administration are
ensured through intelligent request routing and automatic replica ensured through intelligent request routing and automatic replica
relocation (using [Federated ReplicaSets](/docs/tasks/administer-federation/replicaset/). relocation (using [Federated ReplicaSets](/docs/tasks/administer-federation/replicaset/).
Clients are automatically routed, via the shortest network path, to Clients are automatically routed, via the shortest network path, to
@ -26,28 +25,9 @@ Federated Ingress is released as an alpha feature, and supports Google Cloud Pla
GCE and hybrid scenarios involving both) in Kubernetes v1.4. Work is under way to support other cloud GCE and hybrid scenarios involving both) in Kubernetes v1.4. Work is under way to support other cloud
providers such as AWS, and other hybrid cloud scenarios (e.g. services providers such as AWS, and other hybrid cloud scenarios (e.g. services
spanning private on-premise as well as public cloud Kubernetes spanning private on-premise as well as public cloud Kubernetes
clusters). We welcome your feedback. clusters).
* TOC You create Federated Ingresses in much that same way as traditional
{:toc}
## Prerequisites
This guide assumes that you have a running Kubernetes Cluster
Federation installation. If not, then head over to the
[federation admin guide](/docs/admin/federation/) to learn how to
bring up a cluster federation (or have your cluster administrator do
this for you). Other tutorials, for example
[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
by Kelsey Hightower, are also available to help you.
You are also expected to have a basic
[working knowledge of Kubernetes](/docs/getting-started-guides/) in
general, and [Ingress](/docs/concepts/services-networking/ingress/) in particular.
## Overview
Federated Ingresses are created in much that same way as traditional
[Kubernetes Ingresses](/docs/concepts/services-networking/ingress/): by making an API [Kubernetes Ingresses](/docs/concepts/services-networking/ingress/): by making an API
call which specifies the desired properties of your logical ingress point. In the call which specifies the desired properties of your logical ingress point. In the
case of Federated Ingress, this API call is directed to the case of Federated Ingress, this API call is directed to the
@ -57,16 +37,11 @@ API for traditional Kubernetes Services.
Once created, the Federated Ingress automatically: Once created, the Federated Ingress automatically:
1. creates matching Kubernetes Ingress objects in every cluster * Creates matching Kubernetes Ingress objects in every cluster underlying your Cluster Federation
underlying your Cluster Federation, * Ensures that all of these in-cluster ingress objects share the same
2. ensures that all of these in-cluster ingress objects share the same logical global L7 (that is, HTTP(S)) load balancer and IP address
logical global L7 (i.e. HTTP(S)) load balancer and IP address. * Monitors the health and capacity of the service shards (that is, your pods) behind this ingress in each cluster
3. monitors the health and capacity of the service "shards" (i.e. your * Ensures that all client connections are routed to an appropriate healthy backend service endpoint at all times, even in the event of pod, cluster, availability zone or regional outages
pods) behind this ingress in each cluster
4. ensures that all client connections are routed to an appropriate
healthy backend service endpoint at all times, even in the event of
pod, cluster,
availability zone or regional outages.
Note that in the case of Google Cloud, the logical L7 load balancer is Note that in the case of Google Cloud, the logical L7 load balancer is
not a single physical device (which would present both a single point not a single physical device (which would present both a single point
@ -75,17 +50,32 @@ rather a
[truly global, highly available load balancing managed service](https://cloud.google.com/load-balancing/), [truly global, highly available load balancing managed service](https://cloud.google.com/load-balancing/),
globally reachable via a single, static IP address. globally reachable via a single, static IP address.
Clients inside your federated Kubernetes clusters (i.e. Pods) will be Clients inside your federated Kubernetes clusters (Pods) will be
automatically routed to the cluster-local shard of the Federated Service automatically routed to the cluster-local shard of the Federated Service
backing the Ingress in their backing the Ingress in their cluster if it exists and is healthy, or the closest healthy shard in a
cluster if it exists and is healthy, or the closest healthy shard in a
different cluster if it does not. Note that this involves a network different cluster if it does not. Note that this involves a network
trip to the HTTP(s) load balancer, which resides outside your local trip to the HTTP(s) load balancer, which resides outside your local
Kubernetes cluster but inside the same GCP region. Kubernetes cluster but inside the same GCP region.
{% endcapture %}
{% capture prerequisites %}
This document assumes that you have a running Kubernetes Cluster
Federation installation. If not, then see the
[federation admin guide](/docs/admin/federation/) to learn how to
bring up a cluster federation (or have your cluster administrator do
this for you). Other tutorials, for example
[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
by Kelsey Hightower, are also available to help you.
You must also have a basic
[working knowledge of Kubernetes](/docs/getting-started-guides/) in
general, and [Ingress](/docs/concepts/services-networking/ingress/) in particular.
{% endcapture %}
{% capture steps %}
## Creating a federated ingress ## Creating a federated ingress
You can create a federated ingress in any of the usual ways, for example using kubectl: You can create a federated ingress in any of the usual ways, for example, using kubectl:
``` shell ``` shell
kubectl --context=federation-cluster create -f myingress.yaml kubectl --context=federation-cluster create -f myingress.yaml
@ -93,19 +83,19 @@ kubectl --context=federation-cluster create -f myingress.yaml
For example ingress YAML configurations, see the [Ingress User Guide](/docs/concepts/services-networking/ingress/) For example ingress YAML configurations, see the [Ingress User Guide](/docs/concepts/services-networking/ingress/)
The '--context=federation-cluster' flag tells kubectl to submit the The '--context=federation-cluster' flag tells kubectl to submit the
request to the Federation API endpoint, with the appropriate request to the Federation API endpoint, with the appropriate
credentials. If you have not yet configured such a context, visit the credentials. If you have not yet configured such a context, see the
[federation admin guide](/docs/admin/federation/) or one of the [federation admin guide](/docs/admin/federation/) or one of the
[administration tutorials](https://github.com/kelseyhightower/kubernetes-cluster-federation) [administration tutorials](https://github.com/kelseyhightower/kubernetes-cluster-federation)
to find out how to do so. to find out how to do so.
As described above, the Federated Ingress will automatically create The Federated Ingress automatically creates
and maintain matching Kubernetes ingresses in all of the clusters and maintains matching Kubernetes ingresses in all of the clusters
underlying your federation. These cluster-specific ingresses (and underlying your federation. These cluster-specific ingresses (and
their associated ingress controllers) configure and manage the load their associated ingress controllers) configure and manage the load
balancing and health checking infrastructure that ensures that traffic balancing and health checking infrastructure that ensures that traffic
is load balanced to each cluster appropriately. is load balanced to each cluster appropriately.
You can verify this by checking in each of the underlying clusters, for example: You can verify this by checking in each of the underlying clusters. For example:
``` shell ``` shell
kubectl --context=gce-asia-east1a get ingress myingress kubectl --context=gce-asia-east1a get ingress myingress
@ -115,15 +105,15 @@ myingress * 130.211.5.194 80, 443 1m
The above assumes that you have a context named 'gce-asia-east1a' The above assumes that you have a context named 'gce-asia-east1a'
configured in your client for your cluster in that zone. The name and configured in your client for your cluster in that zone. The name and
namespace of the underlying ingress will automatically match those of namespace of the underlying ingress automatically matches those of
the Federated Ingress that you created above (and if you happen to the Federated Ingress that you created above (and if you happen to
have had ingresses of the same name and namespace already existing in have had ingresses of the same name and namespace already existing in
any of those clusters, they will be automatically adopted by the any of those clusters, they will be automatically adopted by the
Federation and updated to conform with the specification of your Federation and updated to conform with the specification of your
Federated Ingress - either way, the end result will be the same). Federated Ingress. Either way, the end result will be the same).
The status of your Federated Ingress will automatically reflect the The status of your Federated Ingress automatically reflects the
real-time status of the underlying Kubernetes ingresses, for example: real-time status of the underlying Kubernetes ingresses. For example:
``` shell ``` shell
kubectl --context=federation-cluster describe ingress myingress kubectl --context=federation-cluster describe ingress myingress
@ -153,34 +143,33 @@ Events:
Note that: Note that:
1. the address of your Federated Ingress * The address of your Federated Ingress
corresponds with the address of all of the corresponds with the address of all of the
underlying Kubernetes ingresses (once these have been allocated - this underlying Kubernetes ingresses (once these have been allocated - this
may take up to a few minutes). may take up to a few minutes).
2. we have not yet provisioned any backend Pods to receive * You have not yet provisioned any backend Pods to receive
the network traffic directed to this ingress (i.e. 'Service the network traffic directed to this ingress (that is, 'Service
Endpoints' behind the service backing the Ingress), so the Federated Ingress does not yet consider these to Endpoints' behind the service backing the Ingress), so the Federated Ingress does not yet consider these to
be healthy shards and will not direct traffic to any of these clusters. be healthy shards and will not direct traffic to any of these clusters.
3. the federation control system will * The federation control system
automatically reconfigure the load balancer controllers in all of the automatically reconfigures the load balancer controllers in all of the
clusters in your federation to make them consistent, and allow clusters in your federation to make them consistent, and allows
them to share global load balancers. But this reconfiguration can them to share global load balancers. But this reconfiguration can
only complete successfully if there are no pre-existing Ingresses in only complete successfully if there are no pre-existing Ingresses in
those clusters (this is a safety feature to prevent accidental those clusters (this is a safety feature to prevent accidental
breakage of existing ingresses). So to ensure that your federated breakage of existing ingresses). So, to ensure that your federated
ingresses function correctly, either start with new, empty clusters, or make ingresses function correctly, either start with new, empty clusters, or make
sure that you delete (and recreate if necessary) all pre-existing sure that you delete (and recreate if necessary) all pre-existing
Ingresses in the clusters comprising your federation. Ingresses in the clusters comprising your federation.
## Adding backend services and pods ## Adding backend services and pods
To render the underlying ingress shards healthy, we need to add To render the underlying ingress shards healthy, you need to add
backend Pods behind the service upon which the Ingress is based. There are several ways to achieve this, but backend Pods behind the service upon which the Ingress is based. There are several ways to achieve this, but
the easiest is to create a Federated Service and the easiest is to create a Federated Service and
Federated Replicaset. Details of how those Federated Replicaset. To
work are covered in the aforementioned user guides - here we'll simply use them, to
create appropriately labelled pods and services in the 13 underlying clusters of create appropriately labelled pods and services in the 13 underlying clusters of
our federation: your federation:
``` shell ``` shell
kubectl --context=federation-cluster create -f services/nginx.yaml kubectl --context=federation-cluster create -f services/nginx.yaml
@ -200,7 +189,7 @@ federated service, each cluster will choose it's own node port for
its cluster-local shard of the service, and these will probably end its cluster-local shard of the service, and these will probably end
up being different, which is not what you want. up being different, which is not what you want.
You can verify this by checking in each of the underlying clusters, for example: You can verify this by checking in each of the underlying clusters. For example:
``` shell ``` shell
kubectl --context=gce-asia-east1a get services nginx kubectl --context=gce-asia-east1a get services nginx
@ -208,14 +197,12 @@ NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx 10.63.250.98 104.199.136.89 80/TCP 9m nginx 10.63.250.98 104.199.136.89 80/TCP 9m
``` ```
## Hybrid cloud capabilities ## Hybrid cloud capabilities
Federations of Kubernetes Clusters can include clusters running in Federations of Kubernetes Clusters can include clusters running in
different cloud providers (e.g. Google Cloud, AWS), and on-premises different cloud providers (for example, Google Cloud, AWS), and on-premises
(e.g. on OpenStack). However, in Kubernetes v1.4, Federated Ingress is only (for example, on OpenStack). However, in Kubernetes v1.4, Federated Ingress is only
supported across Google Cloud clusters. In future versions we intend supported across Google Cloud clusters.
to support hybrid cloud Ingress-based deployments.
## Discovering a federated ingress ## Discovering a federated ingress
@ -225,7 +212,7 @@ the Status.Loadbalancer.Ingress field) that remains static for the lifetime
of the Ingress object (in future, automatically managed DNS names of the Ingress object (in future, automatically managed DNS names
might also be added). All clients (whether internal to your cluster, might also be added). All clients (whether internal to your cluster,
or on the external network or internet) should connect to one of these IP or on the external network or internet) should connect to one of these IP
or DNS addresses. As mentioned above, all client requests are automatically or DNS addresses. All client requests are automatically
routed, via the shortest network path, to a healthy pod in the routed, via the shortest network path, to a healthy pod in the
closest cluster to the origin of the request. So for example, HTTP(S) closest cluster to the origin of the request. So for example, HTTP(S)
requests from internet requests from internet
@ -239,8 +226,7 @@ Europe, the request will be routed to the next closest cluster
Ingresses are backed by Services, which are typically (but not always) Ingresses are backed by Services, which are typically (but not always)
backed by one or more ReplicaSets. For Federated Ingresses, it is backed by one or more ReplicaSets. For Federated Ingresses, it is
common practise to use the federated variants of Services and common practise to use the federated variants of Services and
ReplicaSets for this purpose, as ReplicaSets for this purpose.
described above.
In particular, Federated ReplicaSets ensure that the desired number of In particular, Federated ReplicaSets ensure that the desired number of
pods are kept running in each cluster, even in the event of node pods are kept running in each cluster, even in the event of node
@ -255,16 +241,17 @@ available clusters.
## Troubleshooting ## Troubleshooting
#### I cannot connect to my cluster federation API #### I cannot connect to my cluster federation API.
Check that your
1. Client (typically kubectl) is correctly configured (including API endpoints and login credentials), and Check that your:
1. Client (typically `kubectl`) is correctly configured (including API endpoints and login credentials).
2. Cluster Federation API server is running and network-reachable. 2. Cluster Federation API server is running and network-reachable.
See the [federation admin guide](/docs/admin/federation/) to learn See the [federation admin guide](/docs/admin/federation/) to learn
how to bring up a cluster federation correctly (or have your cluster administrator do this for you), and how to correctly configure your client. how to bring up a cluster federation correctly (or have your cluster administrator do this for you), and how to correctly configure your client.
#### I can create a federated ingress/service/replicaset successfully against the cluster federation API, but no matching ingresses/services/replicasets are created in my underlying clusters #### I can create a Federated Ingress/service/replicaset successfully against the cluster federation API, but no matching ingresses/services/replicasets are created in my underlying clusters.
Check that: Check that:
@ -282,13 +269,13 @@ Check that:
`service-controller` or `replicaset-controller`, `service-controller` or `replicaset-controller`,
errors in the output of `kubectl logs federation-controller-manager --namespace federation`). errors in the output of `kubectl logs federation-controller-manager --namespace federation`).
#### I can create a federated ingress successfully, but request load is not correctly distributed across the underlying clusters #### I can create a federated ingress successfully, but request load is not correctly distributed across the underlying clusters.
Check that: Check that:
1. the services underlying your federated ingress in each cluster have 1. The services underlying your federated ingress in each cluster have
identical node ports. See [above](#creating_a_federated_ingress) for further explanation. identical node ports. See [above](#creating_a_federated_ingress) for further explanation.
2. the load balancer controllers in each of your clusters are of the 2. The load balancer controllers in each of your clusters are of the
correct type ("GLBC") and have been correctly reconfigured by the correct type ("GLBC") and have been correctly reconfigured by the
federation control plane to share a global GCE load balancer (this federation control plane to share a global GCE load balancer (this
should happen automatically). If they of the correct type, and should happen automatically). If they of the correct type, and
@ -300,7 +287,7 @@ Check that:
If this is not the case, check the logs of your federation If this is not the case, check the logs of your federation
controller manager to determine why this automated reconfiguration controller manager to determine why this automated reconfiguration
might be failing. might be failing.
3. no ingresses have been manually created in any of your clusters before the above 3. No ingresses have been manually created in any of your clusters before the above
reconfiguration of the load balancer controller completed reconfiguration of the load balancer controller completed
successfully. Ingresses created before the reconfiguration of successfully. Ingresses created before the reconfiguration of
your GLBC will interfere with the behavior of your federated your GLBC will interfere with the behavior of your federated
@ -310,11 +297,15 @@ Check that:
delete any ingresses created before the cluster joined the delete any ingresses created before the cluster joined the
federation (and had it's GLBC reconfigured), and recreate them if federation (and had it's GLBC reconfigured), and recreate them if
necessary. necessary.
{% endcapture %}
{% capture whatsnext %}
* If you need assistance, use one of the [support channels](http://kubernetes.io/docs/troubleshooting/) to seek assistance.
* For details about use cases that motivated this work, see
[Federation proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/federation.md).
{% endcapture %}
{% include templates/task.md %}
#### This troubleshooting guide did not help me solve my problem
Please use one of our [support channels](http://kubernetes.io/docs/troubleshooting/) to seek assistance.
## For more information
* [Federation proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/federation.md) details use cases that motivated this work.