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

Updates to Ingress #12465

Merged
merged 5 commits into from
Feb 18, 2019
Merged

Updates to Ingress #12465

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9c0db8f
Create ingress-minikube.md
cody-clark Jan 31, 2019
51b8403
Update ingress.md
cody-clark Jan 31, 2019
734f7f4
Create ingress-controllers.md
cody-clark Jan 31, 2019
37a8b85
Update ingress-controllers.md
cody-clark Jan 31, 2019
5f08869
Merge branch 'master' into cody-clark-ingress
zparnold Feb 18, 2019
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
67 changes: 67 additions & 0 deletions content/en/docs/concepts/services-networking/ingress-controllers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
title: Ingress Controllers
reviewers:
content_template: templates/concept
toc_hide: true
---

{{% capture body %}}

## Ingress controllers

In order for the Ingress resource to work, the cluster must have an ingress controller running.
This is unlike other types of controllers, which run as part of the `kube-controller-manager` binary,
and are typically started automatically with a cluster. Choose the ingress controller implementation
that best fits your cluster.

* Kubernetes as a project currently supports and maintains [GCE](https://git.k8s.io/ingress-gce/README.md) and
[nginx](https://git.k8s.io/ingress-nginx/README.md) controllers.

### Additional controllers include:

* [Contour](https://github.com/heptio/contour) is an [Envoy](https://www.envoyproxy.io) based ingress controller
provided and supported by Heptio.
* Citrix provides an [Ingress Controller](https://github.com/citrix/citrix-k8s-ingress-controller) for its hardware (MPX), virtualized (VPX) and [free containerized (CPX) ADC](https://www.citrix.com/products/citrix-adc/cpx-express.html) for [baremetal](https://github.com/citrix/citrix-k8s-ingress-controller/tree/master/deployment/baremetal) and [cloud](https://github.com/citrix/citrix-k8s-ingress-controller/tree/master/deployment) deployments.
* F5 Networks provides [support and maintenance](https://support.f5.com/csp/article/K86859508)
for the [F5 BIG-IP Controller for Kubernetes](http://clouddocs.f5.com/products/connectors/k8s-bigip-ctlr/latest).
* [Gloo](https://gloo.solo.io) is an open-source ingress controller based on [Envoy](https://www.envoyproxy.io) which offers API Gateway functionality with enterprise support from [solo.io](https://www.solo.io).
* [HAProxy](http://www.haproxy.org/) based ingress controller
[jcmoraisjr/haproxy-ingress](https://github.com/jcmoraisjr/haproxy-ingress) which is mentioned on the blog post
[HAProxy Ingress Controller for Kubernetes](https://www.haproxy.com/blog/haproxy_ingress_controller_for_kubernetes/).
[HAProxy Technologies](https://www.haproxy.com/) offers support and maintenance for HAProxy Enterprise and
the ingress controller [jcmoraisjr/haproxy-ingress](https://github.com/jcmoraisjr/haproxy-ingress).
* [Istio](https://istio.io/) based ingress controller
[Control Ingress Traffic](https://istio.io/docs/tasks/traffic-management/ingress/).
* [Kong](https://konghq.com/) offers [community](https://discuss.konghq.com/c/kubernetes) or
[commercial](https://konghq.com/kong-enterprise/) support and maintenance for the
[Kong Ingress Controller for Kubernetes](https://github.com/Kong/kubernetes-ingress-controller).
* [NGINX, Inc.](https://www.nginx.com/) offers support and maintenance for the
[NGINX Ingress Controller for Kubernetes](https://www.nginx.com/products/nginx/kubernetes-ingress-controller).
* [Traefik](https://github.com/containous/traefik) is a fully featured ingress controller
([Let's Encrypt](https://letsencrypt.org), secrets, http2, websocket), and it also comes with commercial
support by [Containous](https://containo.us/services).

## Using multiple Ingress controllers

You may deploy [any number of ingress controllers](https://git.k8s.io/ingress-nginx/docs/user-guide/multiple-ingress.md#multiple-ingress-controllers)
within a cluster. When you create an ingress, you should annotate each ingress with the appropriate
[`ingress.class`](https://git.k8s.io/ingress-gce/docs/faq/README.md#how-do-i-run-multiple-ingress-controllers-in-the-same-cluster)
to indicate which ingress controller should be used if more than one exists within your cluster.

If you do not define a class, your cloud provider may use a default ingress provider.

Ideally, all ingress controllers should fulfill this specification, but the various ingress
controllers operate slightly differently.

{{< note >}}
Make sure you review your ingress controller's documentation to understand the caveats of choosing it.
{{< /note >}}

{{% /capture %}}

{{% capture whatsnext %}}

* Learn more about [Ingress](/docs/concepts/services-networking/ingress/).
* [Set up Ingress on Minikube with the NGINX Controller](/docs/tasks/access-application-cluster/ingress-minikube.md).

{{% /capture %}}
104 changes: 53 additions & 51 deletions content/en/docs/concepts/services-networking/ingress.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ For the sake of clarity, this guide defines the following terms:

Ingress, added in Kubernetes v1.1, exposes HTTP and HTTPS routes from outside the cluster to
{{< link text="services" url="/docs/concepts/services-networking/service/" >}} within the cluster.
Traffic routing is controlled by rules defined on the ingress resource.
Traffic routing is controlled by rules defined on the Ingress resource.

```none
internet
Expand All @@ -35,19 +35,23 @@ Traffic routing is controlled by rules defined on the ingress resource.
[ Services ]
```

An ingress can be configured to give services externally-reachable URLs, load balance traffic, terminate SSL, and offer name based virtual hosting. An [ingress controller](#ingress-controllers) is responsible for fulfilling the ingress, usually with a loadbalancer, though it may also configure your edge router or additional frontends to help handle the traffic.
An Ingress can be configured to give services externally-reachable URLs, load balance traffic, terminate SSL, and offer name based virtual hosting. An [Ingress controller](/docs/concepts/services-networking/ingress-controllers) is responsible for fulfilling the Ingress, usually with a loadbalancer, though it may also configure your edge router or additional frontends to help handle the traffic.

An ingress does not expose arbitrary ports or protocols. Exposing services other than HTTP and HTTPS to the internet typically
An Ingress does not expose arbitrary ports or protocols. Exposing services other than HTTP and HTTPS to the internet typically
uses a service of type [Service.Type=NodePort](/docs/concepts/services-networking/service/#nodeport) or
[Service.Type=LoadBalancer](/docs/concepts/services-networking/service/#loadbalancer).

## Prerequisites

{{< feature-state for_k8s_version="v1.1" state="beta" >}}

Before you start using an ingress, there are a few things you should understand. The ingress is a beta resource. You will need an ingress controller to satisfy an ingress, simply creating the resource will have no effect.
Before you start using an Ingress, there are a few things you should understand. The Ingress is a beta resource.

GCE/Google Kubernetes Engine deploys an [ingress controller](#ingress-controllers) on the master. Review the
{{< note >}}
You must have an [Ingress controller](/docs/concepts/services-networking/ingress-controllers) to satisfy an Ingress. Only creating an Ingress resource has no effect.
{{< /note >}}

GCE/Google Kubernetes Engine deploys an Ingress controller on the master. Review the
[beta limitations](https://github.com/kubernetes/ingress-gce/blob/master/BETA_LIMITATIONS.md#glbc-beta-limitations)
of this controller if you are using GCE/GKE.

Expand Down Expand Up @@ -125,14 +129,14 @@ spec:
servicePort: 80
```

As with all other Kubernetes resources, an ingress needs `apiVersion`, `kind`, and `metadata` fields.
As with all other Kubernetes resources, an Ingress needs `apiVersion`, `kind`, and `metadata` fields.
For general information about working with config files, see [deploying applications](/docs/tasks/run-application/run-stateless-application-deployment/), [configuring containers](/docs/tasks/configure-pod-container/configure-pod-configmap/), [managing resources](/docs/concepts/cluster-administration/manage-deployment/).
Ingress frequently uses annotations to configure some options depending on the ingress controller, an example of which
Ingress frequently uses annotations to configure some options depending on the Ingress controller, an example of which
is the [rewrite-target annotation](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/rewrite/README.md).
Different [ingress controller](#ingress-controllers) support different annotations. Review the documentation for
your choice of ingress controller to learn which annotations are supported.
Different [Ingress controller]((/docs/concepts/services-networking/ingress-controllers)) support different annotations. Review the documentation for
your choice of Ingress controller to learn which annotations are supported.

The ingress [spec](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status)
The Ingress [spec](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status)
has all the information needed to configure a loadbalancer or proxy server. Most importantly, it
contains a list of rules matched against all incoming requests. Ingress resource only supports rules
for directing HTTP traffic.
Expand All @@ -149,26 +153,25 @@ Each http rule contains the following information:
loadbalancer will direct traffic to the referenced service.
* A backend is a combination of service and port names as described in the
[services doc](/docs/concepts/services-networking/service/). HTTP (and HTTPS) requests to the
ingress matching the host and path of the rule will be sent to the listed backend.
Ingress matching the host and path of the rule will be sent to the listed backend.

A default backend is often configured in an ingress controller that will service any requests that do not
A default backend is often configured in an Ingress controller that will service any requests that do not
match a path in the spec.

### Default Backend

An ingress with no rules sends all traffic to a single default backend. The default
backend is typically a configuration option of the [ingress controller](#ingress-controllers)
and is not specified in your ingress resources.
An Ingress with no rules sends all traffic to a single default backend. The default
backend is typically a configuration option of the [Ingress controller](/docs/concepts/services-networking/ingress-controllers) and is not specified in your Ingress resources.

If none of the hosts or paths match the HTTP request in the ingress objects, the traffic is
If none of the hosts or paths match the HTTP request in the Ingress objects, the traffic is
routed to your default backend.

## Types of Ingress

### Single Service Ingress

There are existing Kubernetes concepts that allow you to expose a single Service
(see [alternatives](#alternatives)). You can also do this with an ingress by specifying a
(see [alternatives](#alternatives)). You can also do this with an Ingress by specifying a
*default backend* with no rules.

{{< codenew file="service/networking/ingress.yaml" >}}
Expand All @@ -184,8 +187,8 @@ NAME HOSTS ADDRESS PORTS AGE
test-ingress * 107.178.254.228 80 59s
```

Where `107.178.254.228` is the IP allocated by the ingress controller to satisfy
this ingress.
Where `107.178.254.228` is the IP allocated by the Ingress controller to satisfy
this Ingress.

{{< note >}}
Ingress controllers and load balancers may take a minute or two to allocate an IP address.
Expand All @@ -195,15 +198,15 @@ Until that time you will often see the address listed as `<pending>`.
### Simple fanout

A fanout configuration routes traffic from a single IP address to more than one service,
based on the HTTP URI being requested. An ingress allows you to keep the number of loadbalancers
based on the HTTP URI being requested. An Ingress allows you to keep the number of loadbalancers
down to a minimum. For example, a setup like:

```shell
foo.bar.com -> 178.91.123.132 -> / foo service1:4200
/ bar service2:8080
```

would require an ingress such as:
would require an Ingress such as:

```yaml
apiVersion: extensions/v1beta1
Expand All @@ -227,7 +230,7 @@ spec:
servicePort: 8080
```

When you create the ingress with `kubectl create -f`:
When you create the Ingress with `kubectl create -f`:

```shell
kubectl describe ingress simple-fanout-example
Expand All @@ -252,13 +255,13 @@ Events:
Normal ADD 22s loadbalancer-controller default/test
```

The ingress controller will provision an implementation specific loadbalancer
that satisfies the ingress, as long as the services (`s1`, `s2`) exist.
When it has done so, you will see the address of the loadbalancer at the
The Ingress controller provisions an implementation specific loadbalancer
that satisfies the Ingress, as long as the services (`s1`, `s2`) exist.
When it has done so, you can see the address of the loadbalancer at the
Address field.

{{< note >}}
Depending on the [ingress controller](#ingress-controllers) you are using, you may need to
Depending on the [Ingress controller](/docs/concepts/services-networking/ingress-controllers) you are using, you may need to
create a default-http-backend [Service](/docs/concepts/services-networking/service/).
{{< /note >}}

Expand All @@ -272,7 +275,7 @@ foo.bar.com --| |-> foo.bar.com s1:80
bar.foo.com --| |-> bar.foo.com s2:80
```

The following ingress tells the backing loadbalancer to route requests based on
The following Ingress tells the backing loadbalancer to route requests based on
the [Host header](https://tools.ietf.org/html/rfc7230#section-5.4).

```yaml
Expand All @@ -296,9 +299,9 @@ spec:
servicePort: 80
```

If you create an ingress resource without any hosts defined in the rules, then any
web traffic to the IP address of your ingress controller can be matched without a name based
virtual host being required. For example, the following ingress resource will route traffic
If you create an Ingress resource without any hosts defined in the rules, then any
web traffic to the IP address of your Ingress controller can be matched without a name based
virtual host being required. For example, the following Ingress resource will route traffic
requested for `first.bar.com` to `service1`, `second.foo.com` to `service2`, and any traffic
to the IP address without a hostname defined in request (that is, without a request header being
presented) to `service3`.
Expand Down Expand Up @@ -331,12 +334,12 @@ spec:

### TLS

You can secure an ingress by specifying a [secret](/docs/concepts/configuration/secret)
that contains a TLS private key and certificate. Currently the ingress only
You can secure an Ingress by specifying a [secret](/docs/concepts/configuration/secret)
that contains a TLS private key and certificate. Currently the Ingress only
supports a single TLS port, 443, and assumes TLS termination. If the TLS
configuration section in an ingress specifies different hosts, they will be
configuration section in an Ingress specifies different hosts, they will be
multiplexed on the same port according to the hostname specified through the
SNI TLS extension (provided the ingress controller supports SNI). The TLS secret
SNI TLS extension (provided the Ingress controller supports SNI). The TLS secret
must contain keys named `tls.crt` and `tls.key` that contain the certificate
and private key to use for TLS, e.g.:

Expand All @@ -352,7 +355,7 @@ metadata:
type: kubernetes.io/tls
```

Referencing this secret in an ingress will tell the ingress controller to
Referencing this secret in an Ingress will tell the Ingress controller to
secure the channel from the client to the loadbalancer using TLS. You need to make
sure the TLS secret you created came from a certificate that contains a CN
for `sslexample.foo.com`.
Expand All @@ -378,24 +381,24 @@ spec:
```

{{< note >}}
There is a gap between TLS features supported by various ingress
There is a gap between TLS features supported by various Ingress
controllers. Please refer to documentation on
[nginx](https://git.k8s.io/ingress-nginx/README.md#https),
[GCE](https://git.k8s.io/ingress-gce/README.md#frontend-https), or any other
platform specific ingress controller to understand how TLS works in your environment.
platform specific Ingress controller to understand how TLS works in your environment.
{{< /note >}}

### Loadbalancing

An ingress controller is bootstrapped with some load balancing policy settings
that it applies to all ingress, such as the load balancing algorithm, backend
An Ingress controller is bootstrapped with some load balancing policy settings
that it applies to all Ingress, such as the load balancing algorithm, backend
weight scheme, and others. More advanced load balancing concepts
(e.g. persistent sessions, dynamic weights) are not yet exposed through the
ingress. You can still get these features through the
Ingress. You can still get these features through the
[service loadbalancer](https://github.com/kubernetes/ingress-nginx).

It's also worth noting that even though health checks are not exposed directly
through the ingress, there exist parallel concepts in Kubernetes such as
through the Ingress, there exist parallel concepts in Kubernetes such as
[readiness probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
which allow you to achieve the same end result. Please review the controller
specific docs to see how they handle health checks (
Expand All @@ -404,7 +407,7 @@ specific docs to see how they handle health checks (

## Updating an Ingress

To update an existing ingress to add a new Host, you can update it by editing the resource:
To update an existing Ingress to add a new Host, you can update it by editing the resource:

```shell
kubectl describe ingress test
Expand Down Expand Up @@ -455,7 +458,7 @@ spec:
```

Saving the yaml will update the resource in the API server, which should tell the
ingress controller to reconfigure the loadbalancer.
Ingress controller to reconfigure the loadbalancer.

```shell
kubectl describe ingress test
Expand All @@ -481,25 +484,24 @@ Events:
Normal ADD 45s loadbalancer-controller default/test
```

You can achieve the same by invoking `kubectl replace -f` on a modified ingress yaml file.
You can achieve the same by invoking `kubectl replace -f` on a modified Ingress yaml file.

## Failing across availability zones

Techniques for spreading traffic across failure domains differs between cloud providers.
Please check the documentation of the relevant [ingress controller](#ingress-controllers) for
details. You can also refer to the [federation documentation](/docs/concepts/cluster-administration/federation/)
for details on deploying ingress in a federated cluster.
Please check the documentation of the relevant [Ingress controller](/docs/concepts/services-networking/ingress-controllers) for details. You can also refer to the [federation documentation](/docs/concepts/cluster-administration/federation/)
for details on deploying Ingress in a federated cluster.

## Future Work

Track [SIG Network](https://github.com/kubernetes/community/tree/master/sig-network)
for more details on the evolution of the ingress and related resources. You may also track the
[ingress repository](https://github.com/kubernetes/ingress/tree/master) for more details on the
evolution of various ingress controllers.
[Ingress repository](https://github.com/kubernetes/ingress/tree/master) for more details on the
evolution of various Ingress controllers.

## Alternatives

You can expose a Service in multiple ways that don't directly involve the ingress resource:
You can expose a Service in multiple ways that don't directly involve the Ingress resource:

* Use [Service.Type=LoadBalancer](/docs/concepts/services-networking/service/#loadbalancer)
* Use [Service.Type=NodePort](/docs/concepts/services-networking/service/#nodeport)
Expand All @@ -508,6 +510,6 @@ You can expose a Service in multiple ways that don't directly involve the ingres
{{% /capture %}}

{{% capture whatsnext %}}

* [Set up Ingress on Minikube with the NGINX Controller](/docs/tasks/access-application-cluster/ingress-minikube.md)
{{% /capture %}}

Loading