mirror of https://github.com/istio/istio.io.git
Add documentation on Ingress support (#7012)
* Add documentation on Ingress support Istio has supported Ingress for quite a while, but its not documented. This explains how to use it and configure it. Note to docs reviewers: Gateway is Istio's alternative to Kubernetes' Inrgess object, and we prefer users to use Gateway. However, for reasons like legacy users, we also support Ingress. * fix lint * fix lint * fix lint * improvements . * Apply suggestions from code review Co-Authored-By: Frank Budinsky <frankb@ca.ibm.com> Co-authored-by: Frank Budinsky <frankb@ca.ibm.com>
This commit is contained in:
John Howard
GitHub
parent
e138836ad7
commit
494b0d0219
|
|
@ -8,11 +8,7 @@ aliases:
|
|||
- /docs/tasks/ingress
|
||||
---
|
||||
|
||||
In a Kubernetes environment, the [Kubernetes Ingress Resource](https://kubernetes.io/docs/concepts/services-networking/ingress/)
|
||||
is used to specify services that should be exposed outside the cluster.
|
||||
In an Istio service mesh, a better approach (which also works in both Kubernetes and other environments) is to use a
|
||||
different configuration model, namely [Istio Gateway](/docs/reference/config/networking/gateway/).
|
||||
A `Gateway` allows Istio features such as monitoring and route rules to be applied to traffic entering the cluster.
|
||||
Along with support for Kubernetes [Ingress](/docs/tasks/traffic-management/ingress/kubernetes-ingress/), Istio offers another configuration model, [Istio Gateway](/docs/reference/config/networking/gateway/). A `Gateway` provides more extensive customization and flexibility than `Ingress`, and allows Istio features such as monitoring and route rules to be applied to traffic entering the cluster.
|
||||
|
||||
This task describes how to configure Istio to expose a service outside of the service mesh using an Istio `Gateway`.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,116 @@
|
|||
---
|
||||
title: Ingress (Kubernetes)
|
||||
description: Describes how to configure a Kubernetes Ingress object to expose a service outside of the service mesh.
|
||||
weight: 15
|
||||
keywords: [traffic-management,ingress]
|
||||
---
|
||||
|
||||
This task describes how to configure Istio to expose a service outside of the service mesh cluster, using the Kubernetes [Ingress Resource](https://kubernetes.io/docs/concepts/services-networking/ingress/).
|
||||
|
||||
{{< tip >}}
|
||||
Using the [Istio Gateway](/docs/tasks/traffic-management/ingress/ingress-control/), rather than Ingress, is recommended to make use of the full feature set that Istio offers, such as rich traffic management and security features.
|
||||
{{< /tip >}}
|
||||
|
||||
## Before you begin
|
||||
|
||||
Follow the instructions in the [Before you begin](/docs/tasks/traffic-management/ingress/ingress-control/#before-you-begin) and [Determining the ingress IP and ports](/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports) sections of the [Ingress Gateways task](/docs/tasks/traffic-management/ingress/ingress-control/).
|
||||
|
||||
## Configuring ingress using an Ingress resource
|
||||
|
||||
A [Kubernetes Ingress Resources](https://kubernetes.io/docs/concepts/services-networking/ingress/) exposes HTTP and HTTPS routes from outside the cluster to services within the cluster.
|
||||
|
||||
Let's see how you can configure a `Ingress` on port 80 for HTTP traffic.
|
||||
|
||||
1. Create an Istio `Gateway`:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl apply -f - <<EOF
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
annotations:
|
||||
kubernetes.io/ingress.class: istio
|
||||
name: ingress
|
||||
spec:
|
||||
rules:
|
||||
- host: httpbin.example.com
|
||||
http:
|
||||
paths:
|
||||
- path: /status/*
|
||||
backend:
|
||||
serviceName: httpbin
|
||||
servicePort: 8000
|
||||
EOF
|
||||
{{< /text >}}
|
||||
|
||||
The `kubernetes.io/ingress.class` annotation is required to tell the Istio gateway controller that it should handle this `Ingress`, otherwise it will be ignored.
|
||||
|
||||
1. Access the _httpbin_ service using _curl_:
|
||||
|
||||
{{< text bash >}}
|
||||
$ curl -I -HHost:httpbin.example.com http://$INGRESS_HOST:$INGRESS_PORT/status/200
|
||||
HTTP/1.1 200 OK
|
||||
server: envoy
|
||||
date: Mon, 29 Jan 2018 04:45:49 GMT
|
||||
content-type: text/html; charset=utf-8
|
||||
access-control-allow-origin: *
|
||||
access-control-allow-credentials: true
|
||||
content-length: 0
|
||||
x-envoy-upstream-service-time: 48
|
||||
{{< /text >}}
|
||||
|
||||
Note that you use the `-H` flag to set the _Host_ HTTP header to
|
||||
"httpbin.example.com". This is needed because the `Ingress` is configured to handle "httpbin.example.com",
|
||||
but in your test environment you have no DNS binding for that host and are simply sending your request to the ingress IP.
|
||||
|
||||
1. Access any other URL that has not been explicitly exposed. You should see an HTTP 404 error:
|
||||
|
||||
{{< text bash >}}
|
||||
$ curl -I -HHost:httpbin.example.com http://$INGRESS_HOST:$INGRESS_PORT/headers
|
||||
HTTP/1.1 404 Not Found
|
||||
date: Mon, 29 Jan 2018 04:45:49 GMT
|
||||
server: envoy
|
||||
content-length: 0
|
||||
{{< /text >}}
|
||||
|
||||
## Next Steps
|
||||
|
||||
### TLS
|
||||
|
||||
`Ingress` supports [specifying TLS settings](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). This is supported by Istio, but the referenced `Secret` must exist in the namespace of the `istio-ingressgateway` deployment (typical `istio-system`). [cert-manager](/docs/ops/integrations/certmanager/) can be used to generate these certificates.
|
||||
|
||||
### Specifying path type
|
||||
|
||||
By default, Istio will treat paths as exact matches, unless they end in `/*` or `.*`, in which case they will become prefix matches. Other regular expressions are not supported.
|
||||
|
||||
In Kubernetes 1.18, a new field, `pathType`, was added. This allows explicitly declaring a path as `Exact` or `Prefix`.
|
||||
|
||||
### Specifying `IngressClass`
|
||||
|
||||
In Kubernetes 1.18, a new resource, `IngressClass`, was added, replacing the `kubernetes.io/ingress.class` annotation on the `Ingress` resource. If you are using this resource, you will need to set the `controller` field to `istio.io/ingress-controller`. For example:
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: IngressClass
|
||||
metadata:
|
||||
name: istio
|
||||
spec:
|
||||
controller: istio.io/ingress-controller
|
||||
---
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: ingress
|
||||
spec:
|
||||
ingressClassName: istio
|
||||
...
|
||||
{{< /text >}}
|
||||
|
||||
## Cleanup
|
||||
|
||||
Delete the `Ingress` configuration, and shutdown the [httpbin]({{< github_tree >}}/samples/httpbin) service:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl delete ingress ingress
|
||||
$ kubectl delete --ignore-not-found=true -f @samples/httpbin/httpbin.yaml@
|
||||
{{< /text >}}
|
||||
Loading…
Reference in New Issue