istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Copy edit of Securing Gateways with HTTPS. (#1733)

This commit is contained in:
Stephen Gilson 2018-07-10 14:00:28 -04:00 committed by Martin Taillefer
parent cdf51a4cc0
commit 98b999cdf7
1 changed files with 24 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
content/docs/tasks/traffic-management/secure-ingress/index.md
View File

@ -13,7 +13,7 @@ gateway to expose an HTTP endpoint of a service to external traffic. This task e
## Before you begin ## Before you begin
1. Perform the steps in the [Before you begin](/docs/tasks/traffic-management/ingress#before-you-begin) and [Determining the ingress IP and ports](/docs/tasks/traffic-management/ingress#determining-the-ingress-ip-and-ports) sections of the 1. Perform the steps in the [Before you begin](/docs/tasks/traffic-management/ingress#before-you-begin) and [Determining the ingress IP and ports](/docs/tasks/traffic-management/ingress#determining-the-ingress-ip-and-ports) sections of the
[Control Ingress Traffic](/docs/tasks/traffic-management/ingress) task. After performing those steps you should have Istio and _httpbin_ service deployed, and the environment variables `INGRESS_HOST` and `SECURE_INGRESS_PORT` set. [Control Ingress Traffic](/docs/tasks/traffic-management/ingress) task. After performing those steps you should have Istio and the [httpbin]({{< github_tree >}}/samples/httpbin) service deployed, and the environment variables `INGRESS_HOST` and `SECURE_INGRESS_PORT` set.
1. For macOS users, verify that you use _curl_ compiled with the [LibreSSL](http://www.libressl.org) library: 1. For macOS users, verify that you use _curl_ compiled with the [LibreSSL](http://www.libressl.org) library:
@ -23,11 +23,11 @@ gateway to expose an HTTP endpoint of a service to external traffic. This task e
{{< /text >}} {{< /text >}}
If a version of _LibreSSL_ is printed as in the output above, your _curl_ should work correctly with the If a version of _LibreSSL_ is printed as in the output above, your _curl_ should work correctly with the
instructions in this task. Otherwise, try some other installation of _curl_, for example on a Linux machine. instructions in this task. Otherwise, try another installation of _curl_, for example on a Linux machine.
## Generate client and server certificates and keys ## Generate client and server certificates and keys
For this task you can use your favorite tool to generate certificates and keys. We used [a script](https://github.com/nicholasjackson/mtls-go-example/blob/master/generate.sh) For this task you can use your favorite tool to generate certificates and keys. This example uses [a script](https://github.com/nicholasjackson/mtls-go-example/blob/master/generate.sh)
from the https://github.com/nicholasjackson/mtls-go-example repository. from the https://github.com/nicholasjackson/mtls-go-example repository.
1. Clone the https://github.com/nicholasjackson/mtls-go-example repository: 1. Clone the https://github.com/nicholasjackson/mtls-go-example repository:
@ -48,18 +48,18 @@ from the https://github.com/nicholasjackson/mtls-go-example repository.
$ generate.sh httpbin.example.com <password> $ generate.sh httpbin.example.com <password>
{{< /text >}} {{< /text >}}
The command will generate four directories: `1_root`, `2_intermediate`, `3_application` and `4_client` with client The command will generate four directories: `1_root`, `2_intermediate`, `3_application`, and `4_client` containing the client
and server certificates you will use. and server certificates you use in the procedures below.
## Configure a TLS ingress gateway ## Configure a TLS ingress gateway
In this subsection you configure an ingress gateway with the port 443 to handle HTTPS traffic. You create a secret In this subsection you configure an ingress gateway with port 443 to handle HTTPS traffic. You first create a secret
with a certificate and a private key. Then you create a `Gateway` definition that contains a `server` on the port 443. with a certificate and a private key. Then you create a `Gateway` definition that contains a `server` on port 443.
1. Create a Kubernetes `Secret` to hold the server's certificate and private key. Use `kubectl` to create the secret 1. Create a Kubernetes `Secret` to hold the server's certificate and private key. Use `kubectl` to create the secret
`istio-ingressgateway-certs` in namespace `istio-system` . The Istio gateway will load the secret automatically. `istio-ingressgateway-certs` in namespace `istio-system` . The Istio gateway will load the secret automatically.
> The secret MUST be called `istio-ingressgateway-certs` in the `istio-system` namespace, or it will not > The secret **must** be called `istio-ingressgateway-certs` in the `istio-system` namespace, or it will not
> be mounted and available to the Istio gateway. > be mounted and available to the Istio gateway.
{{< text bash >}} {{< text bash >}}
@ -72,9 +72,9 @@ with a certificate and a private key. Then you create a `Gateway` definition tha
[Role-Based Access Control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) rules to protect [Role-Based Access Control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) rules to protect
it. it.
1. Define a `Gateway` with a `server` section for the port 443. 1. Define a `Gateway` with a `server` section for port 443.
> The location of the certificate and the private key MUST be `/etc/istio/ingressgateway-certs`, or the gateway will fail to load them. > The location of the certificate and the private key **must** be `/etc/istio/ingressgateway-certs`, or the gateway will fail to load them.
{{< text bash >}} {{< text bash >}}
$ cat <<EOF | istioctl create -f - $ cat <<EOF | istioctl create -f -
@ -126,14 +126,14 @@ with a certificate and a private key. Then you create a `Gateway` definition tha
EOF EOF
{{< /text >}} {{< /text >}}
1. Access the _httpbin_ service with HTTPS by sending an `https` request using _curl_ to `SECURE_INGRESS_PORT`. 1. Access the `httpbin` service with HTTPS by sending an `https` request using _curl_ to `SECURE_INGRESS_PORT`.
The `--resolve` flag is used to instruct _curl_ to supply the The `--resolve` flag instructs _curl_ to supply the
[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) value "httpbin.example.com" when accessing the gateway IP [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) value "httpbin.example.com" when accessing the gateway IP
over TLS. The `--cacert` option instructs _curl_ to use your generated certificate to verify the server. over TLS. The `--cacert` option instructs _curl_ to use your generated certificate to verify the server.
By sending the request to the `/status/418` URL path, you get a nice visual clue that your _httpbin_ service was By sending the request to the `/status/418` URL path, you get a nice visual clue that your `httpbin` service was
indeed accessed. The _httpbin_ service will return the indeed accessed. The `httpbin` service will return the
[418 I'm a Teapot](https://tools.ietf.org/html/rfc7168#section-2.3.3) code. [418 I'm a Teapot](https://tools.ietf.org/html/rfc7168#section-2.3.3) code.
{{< text bash >}} {{< text bash >}}
@ -160,11 +160,11 @@ with a certificate and a private key. Then you create a `Gateway` definition tha
`"""` `"""`
{{< /text >}} {{< /text >}}
> It may take time for the gateway definition to propagate and you may get the following error: > It might take time for the gateway definition to propagate so you might get the following error:
> `Failed to connect to httpbin.example.com port <your secure port>: Connection refused`. Wait for a minute and > `Failed to connect to httpbin.example.com port <your secure port>: Connection refused`. Wait for a minute and
> retry the _curl_ call again. > retry the _curl_ call.
Look for the _Server certificate_ section in the output of _curl_, note the line about matching the _common name_: Look for the _Server certificate_ section in the _curl_ output and note the line about matching the _common name_:
`common name: httpbin.example.com (matched)`. According to the line `SSL certificate verify ok` in the output of `common name: httpbin.example.com (matched)`. According to the line `SSL certificate verify ok` in the output of
_curl_, you can be sure that the server's certificate was verified successfully. Note the returned status of 418 and _curl_, you can be sure that the server's certificate was verified successfully. Note the returned status of 418 and
a nice drawing of a teapot. a nice drawing of a teapot.
@ -180,7 +180,7 @@ In this section you extend your gateway's definition from the previous section t
the server will use to verify its clients. Create the secret `istio-ingressgateway-ca-certs` in namespace `istio-system` the server will use to verify its clients. Create the secret `istio-ingressgateway-ca-certs` in namespace `istio-system`
using `kubectl`. The Istio gateway will automatically load the secret. using `kubectl`. The Istio gateway will automatically load the secret.
> The secret MUST be called `istio-ingressgateway-ca-certs` in the `istio-system` namespace, or it will not > The secret **must** be called `istio-ingressgateway-ca-certs` in the `istio-system` namespace, or it will not
> be mounted and available to the Istio gateway. > be mounted and available to the Istio gateway.
{{< text bash >}} {{< text bash >}}
@ -188,9 +188,9 @@ the server will use to verify its clients. Create the secret `istio-ingressgatew
secret "istio-ingressgateway-ca-certs" created secret "istio-ingressgateway-ca-certs" created
{{< /text >}} {{< /text >}}
1. Redefine your previous `Gateway` while changing the `tls` `mode` to `MUTUAL` and specifying `caCertificates`: 1. Redefine your previous `Gateway` to change the `tls` `mode` to `MUTUAL` and specifying `caCertificates`:
> The location of the certificate MUST be `/etc/istio/ingressgateway-ca-certs`, or the gateway > The location of the certificate **must** be `/etc/istio/ingressgateway-ca-certs`, or the gateway
will fail to load them. The file name of the certificate must be identical to the filename you create the secret will fail to load them. The file name of the certificate must be identical to the filename you create the secret
from, in this case `ca-chain.cert.pem`. from, in this case `ca-chain.cert.pem`.
@ -218,15 +218,15 @@ the server will use to verify its clients. Create the secret `istio-ingressgatew
EOF EOF
{{< /text >}} {{< /text >}}
1. Access the _httpbin_ service by HTTPS as in the previous section: 1. Access the `httpbin` service by HTTPS as in the previous section:
{{< text bash >}} {{< text bash >}}
$ curl --resolve httpbin.example.com:$SECURE_INGRESS_PORT:$INGRESS_HOST --cacert 2_intermediate/certs/ca-chain.cert.pem https://httpbin.example.com:$SECURE_INGRESS_PORT/status/418 $ curl --resolve httpbin.example.com:$SECURE_INGRESS_PORT:$INGRESS_HOST --cacert 2_intermediate/certs/ca-chain.cert.pem https://httpbin.example.com:$SECURE_INGRESS_PORT/status/418
curl: (35) error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure curl: (35) error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure
{{< /text >}} {{< /text >}}
> It may take time for the gateway definition to propagate and you may still get _418_. Wait for a minute and retry > It might take time for the gateway definition to propagate so you might still get _418_. Wait for a minute and retry
the _curl_ call again. the _curl_ call.
This time you get an error since the server refuses to accept unauthenticated requests. You have to send a client This time you get an error since the server refuses to accept unauthenticated requests. You have to send a client
certificate and pass _curl_ your private key for signing the request. certificate and pass _curl_ your private key for signing the request.
@ -287,7 +287,7 @@ they have valid values, according to the output of the following commands:
## Cleanup ## Cleanup
1. Delete the `Gateway` configuration, the `VirtualService` and the secrets: 1. Delete the `Gateway` configuration, the `VirtualService`, and the secrets:
{{< text bash >}} {{< text bash >}}
$ istioctl delete gateway httpbin-gateway $ istioctl delete gateway httpbin-gateway