whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improvements to Federated Ingress User Guide.

Browse Source
This commit is contained in:
Quinton Hoole
2016-10-10 16:27:54 -07:00
parent 9c2827ffa1
commit 27840ef8fe
1 changed files with 62 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-guide/federation/federated-ingress.md
+62 -12
View File
@@ -64,12 +64,12 @@ healthy backend service endpoint at all times, even in the event of
pod, cluster, pod, cluster,
availability zone or regional outages. availability zone or regional outages.
Note that in the Note that in the case of Google Cloud, the logical L7 load balancer is
case of Google Cloud, the logical L7 load balancer is not a single physical device (which not a single physical device (which would present both a single point
would present both a single point of failure, and a single global of failure, and a single global network routing choke point), but
network routing choke point), but rather a [truly global, highly available rather a
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 (i.e. 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
@@ -86,13 +86,13 @@ You can create a federated ingress in any of the usual ways, for example using k
``` shell ``` shell
kubectl --context=federation-cluster create -f myingress.yaml kubectl --context=federation-cluster create -f myingress.yaml
``` ```
For example ingress YAML configurations, see the [Ingress User Guide](/docs/user-guide/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, visit 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. TODO: Update links to find out how to do so.
As described above, the Federated Ingress will automatically create As described above, the Federated Ingress will automatically create
and maintain matching Kubernetes ingresses in all of the clusters and maintain matching Kubernetes ingresses in all of the clusters
@@ -147,17 +147,28 @@ Events:
2m 2m 1 {loadbalancer-controller } Normal CREATE ip: 130.211.5.194 2m 2m 1 {loadbalancer-controller } Normal CREATE ip: 130.211.5.194
``` ```
Note the address of your Federated Ingress Note that:
1. 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
Note also that we 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 (i.e. '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
automatically reconfigure the load balancer controllers in all of the
clusters in your federation to make them consistent, and allow
them to share global load balancers. But this reconfiguration can
only complete successfully if there are no pre-existing Ingresses in
those clusters (this is a safety feature to prevent accidental
breakage of existing ingresses). So to ensure that your federated
ingresses function correctly, either start with new, empty clusters, or make
sure that you delete (and recreate if necessary) all pre-existing
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, we 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
@@ -175,6 +186,16 @@ kubectl --context=federation-cluster create -f services/nginx.yaml
kubectl --context=federation-cluster create -f myreplicaset.yaml kubectl --context=federation-cluster create -f myreplicaset.yaml
``` ```
Note that in order for your federated ingress to work correctly on
Google Cloud, the node ports of all of the underlying cluster-local
services need to be identical. If you're using a federated service
this is easy to do. Simply pick a node port that is not already
being used in any of your clusters, and add that to the spec of your
federated service. If you do not specify a node port for your
federated service, each cluster will choose it's own node port for
its cluster-local shard of the service, and these will probably end
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
@@ -258,6 +279,35 @@ 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
Check that:
1. the services underlying your federated ingress in each cluster have
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
correct type ("GLBC") and have been correctly reconfigured by the
federation control plane to share a global GCE load balancer (this
should happen automatically). If they of the correct type, and
have been correctly reconfigured, the UID data item in the GLBC
configmap in each cluster will be identical across all clusters.
See
[the GLBC docs](https://github.com/kubernetes/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid)
for further details.
If this is not the case, check the logs of your federation
controller manager to determine why this automated reconfiguration
might be failing.
3. no ingresses have been manually created in any of your clusters before the above
reconfiguration of the load balancer controller completed
successfully. Ingresses created before the reconfiguration of
your GLBC will interfere with the behavior of your federated
ingresses created after the reconfiguration (see
[the GLBC docs](https://github.com/kubernetes/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid)
for further information. To remedy this,
delete any ingresses created before the cluster joined the
federation (and had it's GLBC reconfigured), and recreate them if
necessary.
#### This troubleshooting guide did not help me solve my problem #### 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. Please use one of our [support channels](http://kubernetes.io/docs/troubleshooting/) to seek assistance.