mirror of https://github.com/knative/docs.git
Update the Auto TLS instruction (#2083)
* initial version of auto tls instruction * Update auto-tls doc to mention namespace cert feature and http01 challenge feature * address comments * fix format * address comments
This commit is contained in:
Zhimin Xiang
Knative Prow Robot
parent
6b1bac1e69
commit
27382eee2c
|
|
@ -6,56 +6,68 @@ type: "docs"
|
|||
---
|
||||
|
||||
If you install and configure cert-manager, you can configure Knative to
|
||||
automatically obtain new TLS certificates and renew existing ones. To learn more
|
||||
about using secure connections in Knative, see
|
||||
automatically obtain new TLS certificates and renew existing ones for Knative
|
||||
Services.
|
||||
To learn more about using secure connections in Knative, see
|
||||
[Configuring HTTPS with TLS certificates](./using-a-tls-cert.md).
|
||||
|
||||
## Automatic TLS provision mode
|
||||
|
||||
Knative supports the following Auto TLS modes:
|
||||
|
||||
1. Using DNS-01 challenge
|
||||
|
||||
In this mode, your cluster needs to be able to talk to your DNS server to verify the ownership of your domain.
|
||||
- **Provision Certificate per namespace is supported when using DNS-01 challenge mode.**
|
||||
- This is the recommended mode for faster certificate provision.
|
||||
- In this mode, a single Certificate will be provisioned per namespace and is reused across the Knative Services within the same namespace.
|
||||
|
||||
- **Provision Certificate per namespace is supported when using DNS-01 challenge mode.**
|
||||
- This is the recommended mode for better certificate islation between Knative Services.
|
||||
- In this mode, a Certificate will be provisioned for each Knative Service.
|
||||
- The TLS effective time is longer as it needs Certificate provision for each Knative Service creation.
|
||||
|
||||
1. Using HTTP-01 challenge
|
||||
|
||||
- In this type, your cluster does not need to be able to talk to your DNS server. You just
|
||||
need to map your domain to the IP of the cluser ingress.
|
||||
- When using HTTP-01 challenge, **a certificate will be provisioned per Knative Service.** Certificate provision per namespace is not supported when using HTTP-01 challenge.
|
||||
|
||||
## Before you begin
|
||||
|
||||
You must meet the following prerequisites to enable automatic certificate
|
||||
provisioning:
|
||||
You must meet the following prerequisites to enable auto TLS:
|
||||
|
||||
- The following must be installed on your Knative cluter:
|
||||
- [Knative Serving](../install/).
|
||||
- [Istio with SDS, version 1.1 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway),
|
||||
- [Istio with SDS, version 1.3 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway),
|
||||
[Contour, version 1.1 or higher](../install/Knative-with-Contour.md),
|
||||
or [Gloo, version 0.18.16 or higher](../install/Knative-with-Gloo.md).
|
||||
Note: Currently, [Ambassador](https://github.com/datawire/ambassador) is unsupported.
|
||||
- [cert-manager version `0.6.1` or higher](./installing-cert-manager.md).
|
||||
- [cert-manager version `0.12.0` or higher](./installing-cert-manager.md).
|
||||
- Your Knative cluster must be configured to use a
|
||||
[custom domain](./using-a-custom-domain.md).
|
||||
- Your DNS provider must be setup and configured to your domain.
|
||||
- If you want to use HTTP-01 challenge, you need to configure your custom
|
||||
domain to map to the IP of ingress. You can achieve this by adding a DNS A record to map the domain to the IP according to the instructions of your DNS provider.
|
||||
|
||||
## Enabling automatic certificate provisioning
|
||||
## Enabling Auto TLS
|
||||
|
||||
To enable support for automatic TLS certificate provisioning in Knative:
|
||||
To enable support for Auto TLS in Knative:
|
||||
|
||||
1. Determine if `networking-certmanager` is already installed by running the
|
||||
following command:
|
||||
### Create cert-manager ClusterIssuer
|
||||
|
||||
```shell
|
||||
kubectl get deployment networking-certmanager -n knative-serving
|
||||
```
|
||||
1. Create and add the `ClusterIssuer` configuration file to your Knative cluster
|
||||
to define who issues the TLS certificates, how requests are validated,
|
||||
and which DNS provider validates those requests.
|
||||
|
||||
1. If `networking-certmanager` is not found, run the following command:
|
||||
#### ClusterIssuer for DNS-01 challenge
|
||||
|
||||
```shell
|
||||
kubectl apply --filename https://github.com/knative/serving/releases/download/{{< version >}}/serving-cert-manager.yaml
|
||||
```
|
||||
|
||||
1. Create and add the `ClusterIssuer` configuration file to your Knative cluster
|
||||
to define who issues the TLS certificates, how requests are validated
|
||||
(`DNS-01`), and which DNS provider validates those requests.
|
||||
|
||||
1. Create the `ClusterIssuer` file:
|
||||
|
||||
Use the cert-manager reference to determine how to configure your
|
||||
`ClusterIssuer` file:
|
||||
|
||||
- See the generic
|
||||
[`ClusterIssuer` example](https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme.html#creating-a-basic-acme-issuer)
|
||||
- Also see the
|
||||
[`DNS-01` example](https://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html)
|
||||
Use the cert-manager reference to determine how to configure your
|
||||
`ClusterIssuer` file:
|
||||
- See the generic
|
||||
[`ClusterIssuer` example](https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme.html#creating-a-basic-acme-issuer)
|
||||
- Also see the
|
||||
[`DNS01` example](https://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html)
|
||||
|
||||
**Example**: Cloud DNS `ClusterIssuer` configuration file:
|
||||
|
||||
|
|
@ -67,11 +79,10 @@ To enable support for automatic TLS certificate provisioning in Knative:
|
|||
[Configuring HTTPS with cert-manager and Google Cloud DNS](./using-cert-manager-on-gcp.md).
|
||||
|
||||
```shell
|
||||
apiVersion: certmanager.k8s.io/v1alpha1
|
||||
apiVersion: cert-manager.io/v1alpha2
|
||||
kind: ClusterIssuer
|
||||
metadata:
|
||||
name: letsencrypt-issuer
|
||||
namespace: cert-manager
|
||||
name: letsencrypt-dns-issuer
|
||||
spec:
|
||||
acme:
|
||||
server: https://acme-v02.api.letsencrypt.org/directory
|
||||
|
|
@ -80,171 +91,231 @@ To enable support for automatic TLS certificate provisioning in Knative:
|
|||
email: myemail@gmail.com
|
||||
privateKeySecretRef:
|
||||
# Set privateKeySecretRef to any unused secret name.
|
||||
name: letsencrypt-issuer
|
||||
dns01:
|
||||
providers:
|
||||
- name: cloud-dns-provider
|
||||
clouddns:
|
||||
# Set this to your GCP project-id
|
||||
project: $PROJECT_ID
|
||||
# Set this to the secret that we publish our service account key
|
||||
# in the previous step.
|
||||
serviceAccountSecretRef:
|
||||
name: cloud-dns-key
|
||||
key: key.json
|
||||
name: letsencrypt-dns-issuer
|
||||
solvers:
|
||||
- dns01:
|
||||
clouddns:
|
||||
# Set this to your GCP project-id
|
||||
project: $PROJECT_ID
|
||||
# Set this to the secret that we publish our service account key
|
||||
# in the previous step.
|
||||
serviceAccountSecretRef:
|
||||
name: cloud-dns-key
|
||||
key: key.json
|
||||
```
|
||||
|
||||
1. Add your `ClusterIssuer` configuration to your Knative cluster by running
|
||||
the following commands, where `<filename>` is the name of the file that
|
||||
you created:
|
||||
#### ClusterIssuer for HTTP-01 challenge
|
||||
|
||||
1. Add the configuration file to Knative:
|
||||
Run the following command to apply the ClusterIssuer for HTT01 challenge:
|
||||
|
||||
```shell
|
||||
kubectl apply -f <filename>.yaml
|
||||
```
|
||||
```shell
|
||||
kubectl apply -f - <<EOF
|
||||
apiVersion: cert-manager.io/v1alpha2
|
||||
kind: ClusterIssuer
|
||||
metadata:
|
||||
name: letsencrypt-http01-issuer
|
||||
spec:
|
||||
acme:
|
||||
privateKeySecretRef:
|
||||
name: letsencrypt
|
||||
server: https://acme-v02.api.letsencrypt.org/directory
|
||||
solvers:
|
||||
- http01:
|
||||
ingress:
|
||||
class: istio
|
||||
EOF
|
||||
```
|
||||
|
||||
1. Ensure that the file is created successfully:
|
||||
1. Ensure that the ClusterIssuer is created successfully:
|
||||
|
||||
```shell
|
||||
kubectl get clusterissuer --namespace cert-manager letsencrypt-issuer --output yaml
|
||||
```
|
||||
```shell
|
||||
kubectl get clusterissuer <cluster-issuer-name> --output yaml
|
||||
```
|
||||
|
||||
Result: The `Status.Conditions` should include `Ready=True`.
|
||||
|
||||
1. Update your
|
||||
[`config-certmanager` ConfigMap](https://github.com/knative/serving/blob/master/config/config-certmanager.yaml)
|
||||
in the `knative-serving` namespace to define your new `ClusterIssuer`
|
||||
configuration and your your DNS provider.
|
||||
|
||||
1. Run the following command to edit your `config-certmanager` ConfigMap:
|
||||
|
||||
```shell
|
||||
kubectl edit configmap config-certmanager --namespace knative-serving
|
||||
```
|
||||
|
||||
1. Add the `issuerRef` and `solverConfig` sections within the `data` section:
|
||||
|
||||
```shell
|
||||
...
|
||||
data:
|
||||
...
|
||||
issuerRef: |
|
||||
kind: ClusterIssuer
|
||||
name: letsencrypt-issuer
|
||||
|
||||
solverConfig: |
|
||||
dns01:
|
||||
provider: cloud-dns-provider
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```shell
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: config-certmanager
|
||||
namespace: knative-serving
|
||||
labels:
|
||||
networking.knative.dev/certificate-provider: cert-manager
|
||||
data:
|
||||
issuerRef: |
|
||||
kind: ClusterIssuer
|
||||
name: letsencrypt-issuer
|
||||
solverConfig: |
|
||||
dns01:
|
||||
provider: cloud-dns-provider
|
||||
```
|
||||
|
||||
1. Ensure that the file was updated successfully:
|
||||
|
||||
```shell
|
||||
kubectl get configmap config-certmanager --namespace knative-serving --output yaml
|
||||
```
|
||||
|
||||
1. Update the
|
||||
[`config-network` ConfigMap](https://github.com/knative/serving/blob/master/config/config-network.yaml)
|
||||
in the `knative-serving` namespace to enable `autoTLS`and specify how HTTP
|
||||
requests are handled:
|
||||
|
||||
1. Run the following command to edit your `config-network` ConfigMap:
|
||||
|
||||
```shell
|
||||
kubectl edit configmap config-network --namespace knative-serving
|
||||
```
|
||||
|
||||
1. Add the `autoTLS: Enabled` attribute under the `data` section:
|
||||
|
||||
```shell
|
||||
...
|
||||
data:
|
||||
...
|
||||
autoTLS: Enabled
|
||||
...
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```shell
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: config-network
|
||||
namespace: knative-serving
|
||||
data:
|
||||
...
|
||||
autoTLS: Enabled
|
||||
...
|
||||
```
|
||||
|
||||
1. Configure how HTTP and HTTPS requests are handled in the
|
||||
[`httpProtocol`](https://github.com/knative/serving/blob/master/config/config-network.yaml#L110)
|
||||
attribute.
|
||||
|
||||
By default, Knative ingress is configured to serve HTTP traffic
|
||||
(`httpProtocol: Enabled`). Now that your cluster is configured to use TLS
|
||||
certificates and handle HTTPS traffic, you can specify whether or not any
|
||||
HTTP traffic is allowed.
|
||||
|
||||
Supported `httpProtocol` values:
|
||||
|
||||
- `Enabled`: Serve HTTP traffic.
|
||||
- `Disabled`: Rejects all HTTP traffic.
|
||||
- `Redirected`: Responds to HTTP request with a `302` redirect to ask the
|
||||
clients to use HTTPS.
|
||||
Result: The `Status.Conditions` should include `Ready=True`.
|
||||
|
||||
|
||||
```shell
|
||||
...
|
||||
data:
|
||||
...
|
||||
autoTLS: Enabled
|
||||
...
|
||||
```
|
||||
### Install networking-certmanager deployment
|
||||
|
||||
Example:
|
||||
1. Determine if `networking-certmanager` is already installed by running the
|
||||
following command:
|
||||
|
||||
```shell
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: config-network
|
||||
namespace: knative-serving
|
||||
data:
|
||||
...
|
||||
autoTLS: Enabled
|
||||
...
|
||||
httpProtocol: Redirected
|
||||
...
|
||||
```
|
||||
```shell
|
||||
kubectl get deployment networking-certmanager -n knative-serving
|
||||
```
|
||||
|
||||
1. Ensure that the file was updated successfully:
|
||||
1. If `networking-certmanager` is not found, run the following command:
|
||||
|
||||
```shell
|
||||
kubectl get configmap config-network --namespace knative-serving --output yaml
|
||||
```
|
||||
```shell
|
||||
kubectl apply --filename https://github.com/knative/serving/releases/download/v{{< version >}}/serving-cert-manager.yaml
|
||||
```
|
||||
|
||||
### Install networking-ns-cert component
|
||||
|
||||
If you choose to use the mode of provisioning certificate per namespace, you need to install `networking-ns-cert` components.
|
||||
|
||||
1. Determine if `networking-ns-cert` deployment is already installed by
|
||||
running the following command:
|
||||
|
||||
```shell
|
||||
kubectl get deployment networking-ns-cert -n knative-serving
|
||||
```
|
||||
|
||||
1. If `networking-ns-cert` deployment is not found, run the following command:
|
||||
|
||||
```shell
|
||||
kubectl apply --filename https://github.com/knative/serving/releases/download/v{{< version >}}/serving-nscert.yaml
|
||||
```
|
||||
|
||||
### Configure config-certmanager ConfigMap
|
||||
|
||||
Update your [`config-certmanager` ConfigMap](https://github.com/knative/serving/blob/master/config/config-certmanager.yaml)
|
||||
in the `knative-serving` namespace to reference your new `ClusterIssuer`.
|
||||
|
||||
1. Run the following command to edit your `config-certmanager` ConfigMap:
|
||||
|
||||
```shell
|
||||
kubectl edit configmap config-certmanager --namespace knative-serving
|
||||
```
|
||||
|
||||
1. Add the `issuerRef` within the `data` section:
|
||||
|
||||
```shell
|
||||
...
|
||||
data:
|
||||
...
|
||||
issuerRef: |
|
||||
kind: ClusterIssuer
|
||||
name: letsencrypt-issuer
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```shell
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: config-certmanager
|
||||
namespace: knative-serving
|
||||
labels:
|
||||
networking.knative.dev/certificate-provider: cert-manager
|
||||
data:
|
||||
issuerRef: |
|
||||
kind: ClusterIssuer
|
||||
name: letsencrypt-http01-issuer
|
||||
```
|
||||
|
||||
`issueRef` defines which `ClusterIssuer` will be used by Knative to issue
|
||||
certificates.
|
||||
|
||||
1. Ensure that the file was updated successfully:
|
||||
|
||||
```shell
|
||||
kubectl get configmap config-certmanager --namespace knative-serving --output yaml
|
||||
```
|
||||
|
||||
### Turn on Auto TLS
|
||||
|
||||
Update the
|
||||
[`config-network` ConfigMap](https://github.com/knative/serving/blob/master/config/config-network.yaml)
|
||||
in the `knative-serving` namespace to enable `autoTLS`and specify how HTTP
|
||||
requests are handled:
|
||||
|
||||
1. Run the following command to edit your `config-network` ConfigMap:
|
||||
|
||||
```shell
|
||||
kubectl edit configmap config-network --namespace knative-serving
|
||||
```
|
||||
|
||||
1. Add the `autoTLS: Enabled` attribute under the `data` section:
|
||||
|
||||
```shell
|
||||
...
|
||||
data:
|
||||
...
|
||||
autoTLS: Enabled
|
||||
...
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```shell
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: config-network
|
||||
namespace: knative-serving
|
||||
data:
|
||||
...
|
||||
autoTLS: Enabled
|
||||
...
|
||||
```
|
||||
|
||||
1. Configure how HTTP and HTTPS requests are handled in the
|
||||
[`httpProtocol`](https://github.com/knative/serving/blob/master/config/config-network.yaml#L110)
|
||||
attribute.
|
||||
|
||||
By default, Knative ingress is configured to serve HTTP traffic
|
||||
(`httpProtocol: Enabled`). Now that your cluster is configured to use TLS
|
||||
certificates and handle HTTPS traffic, you can specify whether or not any
|
||||
HTTP traffic is allowed.
|
||||
|
||||
Supported `httpProtocol` values:
|
||||
|
||||
- `Enabled`: Serve HTTP traffic.
|
||||
- `Disabled`: Rejects all HTTP traffic.
|
||||
- `Redirected`: Responds to HTTP request with a `302` redirect to ask the
|
||||
clients to use HTTPS.
|
||||
|
||||
```shell
|
||||
...
|
||||
data:
|
||||
...
|
||||
autoTLS: Enabled
|
||||
...
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```shell
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: config-network
|
||||
namespace: knative-serving
|
||||
data:
|
||||
...
|
||||
autoTLS: Enabled
|
||||
...
|
||||
httpProtocol: Redirected
|
||||
...
|
||||
```
|
||||
|
||||
**Note:**
|
||||
When using HTTP-01 challenge, `httpProtocol` field has to be set to `Enabled` to make sure HTTP-01 challenge requests can be accepted by the cluster.
|
||||
|
||||
1. Ensure that the file was updated successfully:
|
||||
|
||||
```shell
|
||||
kubectl get configmap config-network --namespace knative-serving --output yaml
|
||||
```
|
||||
|
||||
Congratulations! Knative is now configured to obtain and renew TLS certificates.
|
||||
When your TLS certificate is active on your cluster, your Knative services will
|
||||
be able to handle HTTPS traffic.
|
||||
|
||||
### Verify Auto TLS
|
||||
|
||||
1. Run the following comand to create a Knative Service:
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/knative/docs/master/docs/serving/samples/autoscale-go/service.yaml
|
||||
```
|
||||
|
||||
1. When the certificate is provisioned (which could take up to several minutes depending on
|
||||
the challenge type), you should see something like:
|
||||
```
|
||||
NAME URL LATESTCREATED LATESTREADY READY REASON
|
||||
autoscale-go https://autoscale-go.default.{custom-domain} autoscale-go-6jf85 autoscale-go-6jf85 True
|
||||
```
|
||||
|
||||
Note that the URL will be **https** in this case.
|
||||
Loading…
Reference in New Issue