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

Updating Ingress docs for 1.19 

Co-authored-by: robscott <robertjscott@google.com>
pull/21590/head
Christopher M. Luciano 2020-06-23 15:36:35 -04:00 committed by Rob Scott
parent d48be75067
commit 51f6e23f35
No known key found for this signature in database
GPG Key ID: 90C19B2D4A99C91B
9 changed files with 204 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

204
content/en/docs/concepts/services-networking/ingress.md
View File

@ -7,7 +7,7 @@ weight: 40
--- ---
<!-- overview --> <!-- overview -->
{{< feature-state for_k8s_version="v1.1" state="beta" >}} {{< feature-state for_k8s_version="v1.19" state="stable" >}}
{{< glossary_definition term_id="ingress" length="all" >}} {{< glossary_definition term_id="ingress" length="all" >}}
@ -25,7 +25,7 @@ For clarity, this guide defines the following terms:
## What is Ingress? ## What is Ingress?
[Ingress](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#ingress-v1beta1-networking-k8s-io) exposes HTTP and HTTPS routes from outside the cluster to [Ingress](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#ingress-v1-networking-k8s-io) exposes HTTP and HTTPS routes from outside the cluster to
{{< link text="services" url="/docs/concepts/services-networking/service/" >}} within the cluster. {{< 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.
@ -61,23 +61,7 @@ Make sure you review your Ingress controller's documentation to understand the c
A minimal Ingress resource example: A minimal Ingress resource example:
```yaml {{< codenew file="service/networking/minimal-ingress.yaml" >}}
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: test-ingress
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
rules:
- http:
paths:
- path: /testpath
pathType: Prefix
backend:
serviceName: test
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.
The name of an Ingress object must be a valid The name of an Ingress object must be a valid
@ -100,32 +84,33 @@ Each HTTP rule contains the following information:
* An optional host. In this example, no host is specified, so the rule applies to all inbound * An optional host. In this example, no host is specified, so the rule applies to all inbound
HTTP traffic through the IP address specified. If a host is provided (for example, HTTP traffic through the IP address specified. If a host is provided (for example,
foo.bar.com), the rules apply to that host. foo.bar.com), the rules apply to that host.
* A list of paths (for example, `/testpath`), each of which has an associated backend defined with a `serviceName` * A list of paths (for example, `/testpath`), each of which has an associated backend defined with a `service.Name`
and `servicePort`. Both the host and path must match the content of an incoming request before the and a `service.Port.Name` or `service.Port.Number`. Both the host and path must match the content of an incoming request before the
load balancer directs traffic to the referenced Service. load balancer directs traffic to the referenced Service.
* A backend is a combination of Service and port names as described in the * A backend is a combination of Service and port names as described in the
[Service doc](/docs/concepts/services-networking/service/). HTTP (and HTTPS) requests to the [Service doc](/docs/concepts/services-networking/service/) or a [custom resource backend]() by way of a CRD. HTTP (and HTTPS) requests to the
Ingress that matches the host and path of the rule are sent to the listed backend. Ingress that matches the host and path of the rule are sent to the listed backend.
A default backend is often configured in an Ingress controller to service any requests that do not A `defaultBackend` is often configured in an Ingress controller to service any requests that do not
match a path in the spec. match a path in the spec.
### Default Backend ### DefaultBackend {#default-backend}
An Ingress with no rules sends all traffic to a single default backend. The default An Ingress with no rules sends all traffic to a single default backend. The `defaultBackend` is conventionally a configuration option
backend is typically a configuration option of the [Ingress controller](/docs/concepts/services-networking/ingress-controllers) and is not specified in your Ingress resources. 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. routed to your default backend.
### Path Types ### Path Types
Each path in an Ingress has a corresponding path type. There are three supported Each path in an Ingress is required to have a corresponding path type. Paths
path types: that do not include an explicit `pathType` will fail validation. There are three
supported path types:
* _`ImplementationSpecific`_ (default): With this path type, matching is up to * _`ImplementationSpecific`_: With this path type, matching is up to the
the IngressClass. Implementations can treat this as a separate `pathType` or IngressClass. Implementations can treat this as a separate `pathType` or treat
treat it identically to `Prefix` or `Exact` path types. it identically to `Prefix` or `Exact` path types.
* _`Exact`_: Matches the URL path exactly and with case sensitivity. * _`Exact`_: Matches the URL path exactly and with case sensitivity.
@ -135,9 +120,32 @@ path types:
match for path _p_ if every _p_ is an element-wise prefix of _p_ of the match for path _p_ if every _p_ is an element-wise prefix of _p_ of the
request path. request path.
{{< note >}} {{< note >}} If the last element of the path is a substring of the last
If the last element of the path is a substring of the last element in request path, it is not a match (for example: `/foo/bar` matches`/foo/bar/baz`, but does not match `/foo/barbaz`). element in request path, it is not a match (for example: `/foo/bar`
{{< /note >}} matches`/foo/bar/baz`, but does not match `/foo/barbaz`). {{< /note >}}
### Examples
| Kind | Path(s) | Request path(s) | Matches? |
|--------|---------------------------------|-------------------------------|------------------------------------|
| Prefix | `/` | (all paths) | Yes |
| Exact | `/foo` | `/foo` | Yes |
| Exact | `/foo` | `/bar` | No |
| Exact | `/foo` | `/foo/` | No |
| Exact | `/foo/` | `/foo` | No |
| Prefix | `/foo` | `/foo`, `/foo/` | Yes |
| Prefix | `/foo/` | `/foo`, `/foo/` | Yes |
| Prefix | `/aaa/bb` | `/aaa/bbb` | No |
| Prefix | `/aaa/bbb` | `/aaa/bbb` | Yes |
| Prefix | `/aaa/bbb/` | `/aaa/bbb` | Yes, ignores trailing slash |
| Prefix | `/aaa/bbb` | `/aaa/bbb/` | Yes, matches trailing slash |
| Prefix | `/aaa/bbb` | `/aaa/bbb/ccc` | Yes, matches subpath |
| Prefix | `/aaa/bbb` | `/aaa/bbbxyz` | No, does not match string prefix |
| Prefix | `/`, `/aaa` | `/aaa/ccc` | Yes, matches `/aaa` prefix |
| Prefix | `/`, `/aaa`, `/aaa/bbb` | `/aaa/bbb` | Yes, matches `/aaa/bbb` prefix |
| Prefix | `/`, `/aaa`, `/aaa/bbb` | `/ccc` | Yes, matches `/` prefix |
| Prefix | `/aaa` | `/ccc` | No, uses default backend |
| Mixed | `/foo` (Prefix), `/foo` (Exact) | `/foo` | Yes, prefers Exact |
#### Multiple Matches #### Multiple Matches
In some cases, multiple paths within an Ingress will match a request. In those In some cases, multiple paths within an Ingress will match a request. In those
@ -152,18 +160,7 @@ configuration. Each Ingress should specify a class, a reference to an
IngressClass resource that contains additional configuration including the name IngressClass resource that contains additional configuration including the name
of the controller that should implement the class. of the controller that should implement the class.
```yaml {{< codenew file="service/networking/external-lb.yaml" >}}
apiVersion: networking.k8s.io/v1beta1
kind: IngressClass
metadata:
name: external-lb
spec:
controller: example.com/ingress-controller
parameters:
apiGroup: k8s.example.com/v1alpha
kind: IngressParameters
name: external-lb
```
IngressClass resources contain an optional parameters field. This can be used to IngressClass resources contain an optional parameters field. This can be used to
reference additional configuration for this class. reference additional configuration for this class.
@ -203,18 +200,18 @@ 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. *default backend* with no rules.
{{< codenew file="service/networking/ingress.yaml" >}} {{< codenew file="service/networking/test-ingress.yaml" >}}
If you create it using `kubectl apply -f` you should be able to view the state If you create it using `kubectl apply -f` you should be able to view the state
of the Ingress you just added: of the Ingress you just added:
```shell ```
kubectl get ingress test-ingress kubectl get ingress test-ingress
``` ```
``` ```
NAME HOSTS ADDRESS PORTS AGE NAME CLASS HOSTS ADDRESS PORTS AGE
test-ingress * 203.0.113.123 80 59s test-ingress external-lb * 203.0.113.123 80 59s
``` ```
Where `203.0.113.123` is the IP allocated by the Ingress controller to satisfy Where `203.0.113.123` is the IP allocated by the Ingress controller to satisfy
@ -231,34 +228,14 @@ A fanout configuration routes traffic from a single IP address to more than one
based on the HTTP URI being requested. An Ingress allows you to keep the number of load balancers based on the HTTP URI being requested. An Ingress allows you to keep the number of load balancers
down to a minimum. For example, a setup like: down to a minimum. For example, a setup like:
```none ```
foo.bar.com -> 178.91.123.132 -> / foo service1:4200 foo.bar.com -> 178.91.123.132 -> / foo service1:4200
/ bar service2:8080 / bar service2:8080
``` ```
would require an Ingress such as: would require an Ingress such as:
```yaml {{< codenew file="service/networking/simple-fanout-example.yaml" >}}
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: simple-fanout-example
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
rules:
- host: foo.bar.com
http:
paths:
- path: /foo
backend:
serviceName: service1
servicePort: 4200
- path: /bar
backend:
serviceName: service2
servicePort: 8080
```
When you create the Ingress with `kubectl apply -f`: When you create the Ingress with `kubectl apply -f`:
@ -277,8 +254,6 @@ Rules:
foo.bar.com foo.bar.com
/foo service1:4200 (10.8.0.90:4200) /foo service1:4200 (10.8.0.90:4200)
/bar service2:8080 (10.8.0.91:8080) /bar service2:8080 (10.8.0.91:8080)
Annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
Events: Events:
Type Reason Age From Message Type Reason Age From Message
---- ------ ---- ---- ------- ---- ------ ---- ---- -------
@ -309,26 +284,7 @@ bar.foo.com --| |-> bar.foo.com service2:80
The following Ingress tells the backing load balancer to route requests based on The following Ingress tells the backing load balancer to route requests based on
the [Host header](https://tools.ietf.org/html/rfc7230#section-5.4). the [Host header](https://tools.ietf.org/html/rfc7230#section-5.4).
```yaml {{< codenew file="service/networking/name-virtual-host-ingress.yaml" >}}
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: name-virtual-host-ingress
spec:
rules:
- host: foo.bar.com
http:
paths:
- backend:
serviceName: service1
servicePort: 80
- host: bar.foo.com
http:
paths:
- backend:
serviceName: service2
servicePort: 80
```
If you create an Ingress resource without any hosts defined in the rules, then any 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 web traffic to the IP address of your Ingress controller can be matched without a name based
@ -339,31 +295,7 @@ requested for `first.bar.com` to `service1`, `second.foo.com` to `service2`, and
to the IP address without a hostname defined in request (that is, without a request header being to the IP address without a hostname defined in request (that is, without a request header being
presented) to `service3`. presented) to `service3`.
```yaml {{< codenew file="service/networking/name-virtual-host-ingress-no-third-host.yaml" >}}
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: name-virtual-host-ingress
spec:
rules:
- host: first.bar.com
http:
paths:
- backend:
serviceName: service1
servicePort: 80
- host: second.foo.com
http:
paths:
- backend:
serviceName: service2
servicePort: 80
- http:
paths:
- backend:
serviceName: service3
servicePort: 80
```
### TLS ### TLS
@ -393,25 +325,7 @@ secure the channel from the client to the load balancer using TLS. You need to m
sure the TLS secret you created came from a certificate that contains a Common sure the TLS secret you created came from a certificate that contains a Common
Name (CN), also known as a Fully Qualified Domain Name (FQDN) for `sslexample.foo.com`. Name (CN), also known as a Fully Qualified Domain Name (FQDN) for `sslexample.foo.com`.
```yaml {{< codenew file="service/networking/tls-example-ingress.yaml" >}}
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: tls-example-ingress
spec:
tls:
- hosts:
- sslexample.foo.com
secretName: testsecret-tls
rules:
- host: sslexample.foo.com
http:
paths:
- path: /
backend:
serviceName: service1
servicePort: 80
```
{{< note >}} {{< note >}}
There is a gap between TLS features supported by various Ingress There is a gap between TLS features supported by various Ingress
@ -478,16 +392,22 @@ spec:
http: http:
paths: paths:
- backend: - backend:
serviceName: service1 service:
servicePort: 80 name: service1
port:
number: 80
path: /foo path: /foo
pathType: Prefix
- host: bar.baz.com - host: bar.baz.com
http: http:
paths: paths:
- backend: - backend:
serviceName: service2 service:
servicePort: 80 name: service2
port:
number: 80
path: /foo path: /foo
pathType: Prefix
.. ..
``` ```

10
content/en/examples/service/networking/external-lb.yaml Normal file
View File

@ -0,0 +1,10 @@
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: external-lb
spec:
controller: example.com/ingress-controller
parameters:
apiGroup: k8s.example.com
kind: IngressParameters
name: external-lb

9
content/en/examples/service/networking/ingress.yaml
View File

@ -1,9 +0,0 @@
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: test-ingress
spec:
backend:
serviceName: testsvc
servicePort: 80

17
content/en/examples/service/networking/minimal-ingress.yaml Normal file
View File

@ -0,0 +1,17 @@
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: minimal-ingress
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
rules:
- http:
paths:
- path: /testpath
pathType: Prefix
backend:
service:
name: test
port:
number: 80

35
content/en/examples/service/networking/name-virtual-host-ingress-no-third-host.yaml Normal file
View File

@ -0,0 +1,35 @@
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: name-virtual-host-ingress-no-third-host
spec:
rules:
- host: first.bar.com
http:
paths:
- pathType: Prefix
path: "/"
backend:
service:
name: service1
port:
number: 80
- host: second.bar.com
http:
paths:
- pathType: Prefix
path: "/"
backend:
service:
name: service2
port:
number: 80
- http:
paths:
- pathType: Prefix
path: "/"
backend:
service:
name: service3
port:
number: 80

26
content/en/examples/service/networking/name-virtual-host-ingress.yaml Normal file
View File

@ -0,0 +1,26 @@
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: name-virtual-host-ingress
spec:
rules:
- host: foo.bar.com
http:
paths:
- pathType: Prefix
path: "/"
backend:
service:
name: service1
port:
number: 80
- host: bar.foo.com
http:
paths:
- pathType: Prefix
path: "/"
backend:
service:
name: service2
port:
number: 80

23
content/en/examples/service/networking/simple-fanout-example.yaml Normal file
View File

@ -0,0 +1,23 @@
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: simple-fanout-example
spec:
rules:
- host: foo.bar.com
http:
paths:
- path: /foo
pathType: Prefix
backend:
service:
name: service1
port:
number: 4200
- path: /bar
pathType: Prefix
backend:
service:
name: service2
port:
number: 8080

10
content/en/examples/service/networking/test-ingress.yaml Normal file
View File

@ -0,0 +1,10 @@
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: test-ingress
spec:
defaultBackend:
service:
name: test
port:
number: 80

20
content/en/examples/service/networking/tls-example-ingress.yaml Normal file
View File

@ -0,0 +1,20 @@
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: tls-example-ingress
spec:
tls:
- hosts:
- https-example.foo.com
secretName: testsecret-tls
rules:
- host: https-example.foo.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: service1
port:
number: 80