From 0acc7f399624fd73503505cc4d07c673092e86cf Mon Sep 17 00:00:00 2001 From: paulbattagliag Date: Sun, 14 May 2017 16:58:39 -0700 Subject: [PATCH] Update ingress.md --- docs/tasks/administer-federation/ingress.md | 155 +++++++++----------- 1 file changed, 73 insertions(+), 82 deletions(-) diff --git a/docs/tasks/administer-federation/ingress.md b/docs/tasks/administer-federation/ingress.md index f8b81b6b3f..a9d17fb3c6 100644 --- a/docs/tasks/administer-federation/ingress.md +++ b/docs/tasks/administer-federation/ingress.md @@ -4,15 +4,14 @@ redirect_from: - "/docs/user-guide/federation/federated-ingress/" - "/docs/user-guide/federation/federated-ingress.html" --- - -This guide explains how to use Kubernetes Federated Ingress to deploy +{% capture overview %} +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 multiple Kubernetes clusters. As of v1.4, clusters hosted in Google Cloud (both GKE and GCE, or both) are supported. This makes it easy to deploy a service that reliably serves HTTP(S) traffic originating from web clients around the globe on a single, static IP -address. Low -network latency, high fault tolerance and easy administration are +address. Low network latency, high fault tolerance and easy administration are ensured through intelligent request routing and automatic replica relocation (using [Federated ReplicaSets](/docs/tasks/administer-federation/replicaset/). 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 providers such as AWS, and other hybrid cloud scenarios (e.g. services spanning private on-premise as well as public cloud Kubernetes -clusters). We welcome your feedback. +clusters). -* TOC -{: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 +You create Federated Ingresses in much that same way as traditional [Kubernetes Ingresses](/docs/concepts/services-networking/ingress/): by making an API call which specifies the desired properties of your logical ingress point. In 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: -1. creates matching Kubernetes Ingress objects in every cluster -underlying your Cluster Federation, -2. ensures that all of these in-cluster ingress objects share the same - logical global L7 (i.e. HTTP(S)) load balancer and IP address. -3. monitors the health and capacity of the service "shards" (i.e. your - 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. +* Creates matching Kubernetes Ingress objects in every cluster underlying your Cluster Federation +* Ensures that all of these in-cluster ingress objects share the same + logical global L7 (that is, 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 +* 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 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/), 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 -backing the Ingress in their -cluster if it exists and is healthy, or the closest healthy shard in a +backing the Ingress in their 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 trip to the HTTP(s) load balancer, which resides outside your local 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 -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 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/) The '--context=federation-cluster' flag tells kubectl to submit the 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 [administration tutorials](https://github.com/kelseyhightower/kubernetes-cluster-federation) to find out how to do so. -As described above, the Federated Ingress will automatically create -and maintain matching Kubernetes ingresses in all of the clusters +The Federated Ingress automatically creates +and maintains matching Kubernetes ingresses in all of the clusters underlying your federation. These cluster-specific ingresses (and their associated ingress controllers) configure and manage the load balancing and health checking infrastructure that ensures that traffic 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 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' 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 have had ingresses of the same name and namespace already existing in any of those clusters, they will be automatically adopted by the 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 -real-time status of the underlying Kubernetes ingresses, for example: +The status of your Federated Ingress automatically reflects the +real-time status of the underlying Kubernetes ingresses. For example: ``` shell kubectl --context=federation-cluster describe ingress myingress @@ -153,34 +143,33 @@ Events: Note that: -1. the address of your Federated Ingress +* The address of your Federated Ingress corresponds with the address of all of the underlying Kubernetes ingresses (once these have been allocated - this may take up to a few minutes). -2. we have not yet provisioned any backend Pods to receive -the network traffic directed to this ingress (i.e. 'Service +* You have not yet provisioned any backend Pods to receive +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 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 +* The federation control system +automatically reconfigures the load balancer controllers in all of the +clusters in your federation to make them consistent, and allows 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 +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 -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 the easiest is to create a Federated Service and -Federated Replicaset. Details of how those -work are covered in the aforementioned user guides - here we'll simply use them, to +Federated Replicaset. To create appropriately labelled pods and services in the 13 underlying clusters of -our federation: +your federation: ``` shell 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 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 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 ``` - ## Hybrid cloud capabilities Federations of Kubernetes Clusters can include clusters running in -different cloud providers (e.g. Google Cloud, AWS), and on-premises -(e.g. on OpenStack). However, in Kubernetes v1.4, Federated Ingress is only -supported across Google Cloud clusters. In future versions we intend -to support hybrid cloud Ingress-based deployments. +different cloud providers (for example, Google Cloud, AWS), and on-premises +(for example, on OpenStack). However, in Kubernetes v1.4, Federated Ingress is only +supported across Google Cloud clusters. ## 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 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 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 closest cluster to the origin of the request. So for example, HTTP(S) 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) backed by one or more ReplicaSets. For Federated Ingresses, it is common practise to use the federated variants of Services and -ReplicaSets for this purpose, as -described above. +ReplicaSets for this purpose. In particular, Federated ReplicaSets ensure that the desired number of pods are kept running in each cluster, even in the event of node @@ -255,16 +241,17 @@ available clusters. ## Troubleshooting -#### I cannot connect to my cluster federation API -Check that your +#### I cannot connect to my cluster federation API. -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. 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. -#### 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: @@ -282,13 +269,13 @@ Check that: `service-controller` or `replicaset-controller`, 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: -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. -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 federation control plane to share a global GCE load balancer (this 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 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 +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 @@ -310,11 +297,15 @@ Check that: delete any ingresses created before the cluster joined the federation (and had it's GLBC reconfigured), and recreate them if necessary. +{% endcapture %} -#### 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. +{% 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 %} + + + +