From 83b38c42cac8b2f171e5e523ac34a51acab0a6e0 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Tue, 31 May 2022 12:02:37 -0500 Subject: [PATCH] Fix values and general cleanup (#4980) * fix values and general cleanup * fix whitespace * fix bullets --- config/nav.yml | 2 +- docs/serving/using-a-custom-domain.md | 41 ++++---- docs/serving/using-auto-tls.md | 129 ++++++++++++-------------- 3 files changed, 81 insertions(+), 91 deletions(-) diff --git a/config/nav.yml b/config/nav.yml index 65d2699e9..457ed617e 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -115,7 +115,7 @@ nav: - Configuring HTTPS connections: serving/using-a-tls-cert.md - Enabling auto-TLS certs: serving/using-auto-tls.md - Configuring the ingress gateway: serving/setting-up-custom-ingress-gateway.md - - Changing the default domain: serving/using-a-custom-domain.md + - Configuring domain names: serving/using-a-custom-domain.md - Converting a Kubernetes Deployment to a Knative Service: serving/convert-deployment-to-knative-service.md # Serving config - Serving configuration: diff --git a/docs/serving/using-a-custom-domain.md b/docs/serving/using-a-custom-domain.md index 05738fc05..3054b4b17 100644 --- a/docs/serving/using-a-custom-domain.md +++ b/docs/serving/using-a-custom-domain.md @@ -1,29 +1,32 @@ -# Default domain name settings +# Configuring domain names -The fully qualified domain name for a route by default is `{route}.{namespace}.{default-domain}`. Knative Serving routes use `example.com` as the default domain. +You can customize the domain of an individual Knative Service, or set a global default domain for all Services created on a cluster. The fully qualified domain name for a route by default is `{route}.{namespace}.example.com`. -You can change the default domain by modifying the [`config-domain` ConfigMap](https://github.com/knative/serving/blob/main/config/core/configmaps/domain.yaml). +## Configuring a domain for a single Knative Service -!!! warning - Customizing a domain using this ConfigMap affects your cluster globally. If you want to customize the domain of an individual Service, use [`DomainMapping`](services/custom-domains.md) instead. +If you want to customize the domain of an individual Service, see the documentation about [`DomainMapping`](services/custom-domains.md). -## Procedure +## Configuring the default domain for all Knative Services on a cluster + +You can change the default domain for all Knative Services on a cluster by modifying the [`config-domain` ConfigMap](https://github.com/knative/serving/blob/main/config/core/configmaps/domain.yaml). + +### Procedure 1. Open the `config-domain` ConfigMap in your default text editor: - ```bash - kubectl edit configmap config-domain -n knative-serving - ``` + ```bash + kubectl edit configmap config-domain -n knative-serving + ``` -1. Edit the file to replace `example.com` with the domain you want to use, then remove the `_example` key and save your changes. In this example, `mydomain.com` is configured as the domain for all routes: +1. Edit the file to replace `example.com` with the domain you want to use, then remove the `_example` key and save your changes. In this example, `knative.dev` is configured as the domain for all routes: - ```yaml - apiVersion: v1 - data: - mydomain.com: "" - kind: ConfigMap - [...] - ``` + ```yaml + apiVersion: v1 + data: + knative.dev: "" + kind: ConfigMap + [...] + ``` If you have an existing deployment, Knative reconciles the change made to the ConfigMap, and automatically updates the host name for all of the deployed Services and Routes. @@ -50,7 +53,7 @@ To make your domain publicly accessible, you must update your DNS provider to po creating additional DNS entries. ```dns - *.default.mydomain.com 59 IN A 35.237.28.44 + *.default.knative.dev 59 IN A 35.237.28.44 ``` 1. Create an A record to point from the fully qualified domain name to the IP @@ -58,7 +61,7 @@ To make your domain publicly accessible, you must update your DNS provider to po Service or Route created. ```dns - helloworld-go.default.mydomain.com 59 IN A 35.237.28.44 + helloworld-go.default.knative.dev 59 IN A 35.237.28.44 ``` 1. After the domain update has propagated, you can access your app by using the fully qualified domain name of the deployed route. diff --git a/docs/serving/using-auto-tls.md b/docs/serving/using-auto-tls.md index 3d5603814..b5e3ef892 100644 --- a/docs/serving/using-auto-tls.md +++ b/docs/serving/using-auto-tls.md @@ -1,4 +1,4 @@ -# Enabling automatic TLS certificate provisioning +# Enabling auto-TLS certs If you install and configure cert-manager, you can configure Knative to automatically obtain new TLS certificates and renew existing ones for Knative @@ -10,12 +10,15 @@ Services. To learn more about using secure connections in Knative, see The following must be installed on your Knative cluster: - [Knative Serving](../install/yaml-install/serving/install-serving-with-yaml.md). + - A Networking layer such as Kourier, Istio with SDS v1.3 or higher, or Contour v1.1 or higher. See [Install a networking layer](../install/yaml-install/serving/install-serving-with-yaml.md#install-a-networking-layer) or [Istio with SDS, version 1.3 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway). - - [`cert-manager` version `1.0.0` or higher](../install/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. @@ -26,14 +29,15 @@ 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. + - 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 Knative Service is supported when using DNS-01 challenge mode.** - - This is the recommended mode for better certificate isolation 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. + - This is the recommended mode for better certificate isolation 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 @@ -68,7 +72,7 @@ and which DNS provider validates those requests. server: https://acme-v02.api.letsencrypt.org/directory # This will register an issuer with LetsEncrypt. Replace # with your admin email address. - email: myemail@gmail.com + email: test-email@knative.dev privateKeySecretRef: # Set privateKeySecretRef to any unused secret name. name: letsencrypt-dns-issuer @@ -146,7 +150,7 @@ wildcard certificate like `*.my-ns.example.com`. 1. If `net-certmanager-controller` is not found, run the following command: ```bash - kubectl apply --filename {{ artifact( repo="net-certmanager", file="release.yaml") }} + kubectl apply -f {{ artifact( repo="net-certmanager", file="release.yaml") }} ``` ### Provisioning certificates per namespace (wildcard certificates) @@ -183,21 +187,12 @@ in the `knative-serving` namespace to reference your new `ClusterIssuer`. 1. Run the following command to edit your `config-certmanager` ConfigMap: ```bash - kubectl edit configmap config-certmanager --namespace knative-serving + kubectl edit configmap config-certmanager -n knative-serving ``` 1. Add the `issuerRef` within the `data` section: - ```bash - data: - issuerRef: | - kind: ClusterIssuer - name: letsencrypt-http01-issuer - ``` - - Example: - - ```bash + ```yaml apiVersion: v1 kind: ConfigMap metadata: @@ -211,38 +206,28 @@ in the `knative-serving` namespace to reference your new `ClusterIssuer`. name: letsencrypt-http01-issuer ``` - `issueRef` defines which `ClusterIssuer` will be used by Knative to issue + `issueRef` defines which `ClusterIssuer` is used by Knative to issue certificates. 1. Ensure that the file was updated successfully: ```bash - kubectl get configmap config-certmanager --namespace knative-serving --output yaml + kubectl get configmap config-certmanager -n knative-serving -o yaml ``` ### Turn on Auto TLS -Update the -[`config-network` ConfigMap](https://github.com/knative/serving/blob/main/config/core/configmaps/network.yaml) -in the `knative-serving` namespace to enable `auto-tls` and specify how HTTP -requests are handled: +Update the [`config-network` ConfigMap](https://github.com/knative/serving/blob/main/config/core/configmaps/network.yaml) in the `knative-serving` namespace to enable `auto-tls` and specify how HTTP requests are handled: 1. Run the following command to edit your `config-network` ConfigMap: ```bash - kubectl edit configmap config-network --namespace knative-serving + kubectl edit configmap config-network -n knative-serving ``` 1. Add the `auto-tls: Enabled` attribute under the `data` section: - ```bash - data: - auto-tls: Enabled - ``` - - Example: - - ```bash + ```yaml apiVersion: v1 kind: ConfigMap metadata: @@ -254,9 +239,7 @@ requests are handled: ... ``` -1. Configure how HTTP and HTTPS requests are handled in the - [`http-protocol`](https://github.com/knative/serving/blob/main/config/core/configmaps/network.yaml#L109) - attribute. +1. Configure how HTTP and HTTPS requests are handled in the [`http-protocol`](https://github.com/knative/serving/blob/main/config/core/configmaps/network.yaml#L109) attribute. By default, Knative ingress is configured to serve HTTP traffic (`http-protocol: Enabled`). Now that your cluster is configured to use TLS @@ -270,25 +253,25 @@ requests are handled: - `Redirected`: Responds to HTTP request with a `302` redirect to ask the clients to use HTTPS. - ```bash - data: - http-protocol: Redirected - ``` + ```yaml + data: + http-protocol: Redirected + ``` - Example: + Example: - ```bash - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-network - namespace: knative-serving - data: - ... - auto-tls: Enabled - http-protocol: Redirected - ... - ``` + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-network + namespace: knative-serving + data: + ... + auto-tls: Enabled + http-protocol: Redirected + ... + ``` !!! note When using HTTP-01 challenge, `http-protocol` field has to be set to `Enabled` to make sure HTTP-01 challenge requests can be accepted by the cluster. @@ -296,7 +279,7 @@ requests are handled: 1. Ensure that the file was updated successfully: ```bash - kubectl get configmap config-network --namespace knative-serving --output yaml + kubectl get configmap config-network -n knative-serving -o yaml ``` Congratulations! Knative is now configured to obtain and renew TLS certificates. @@ -306,13 +289,14 @@ be able to handle HTTPS traffic. ### Verify Auto TLS 1. Run the following comand to create a Knative Service: + ```bash kubectl apply -f https://raw.githubusercontent.com/knative/docs/main/docs/serving/autoscaling/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: - ``` + ```bash NAME URL LATESTCREATED LATESTREADY READY REASON autoscale-go https://autoscale-go.default.{custom-domain} autoscale-go-6jf85 autoscale-go-6jf85 True ``` @@ -326,17 +310,20 @@ If you have Auto TLS enabled in your cluster, you can choose to disable Auto TLS Using the previous `autoscale-go` example: 1. Edit the service using `kubectl edit service.serving.knative.dev/autoscale-go -n default` and add the annotation: -```yaml - apiVersion: serving.knative.dev/v1 - kind: Service - metadata: - annotations: - ... - networking.knative.dev/disable-auto-tls: "true" - ... -``` -2. The service URL should now be **http**, indicating that AutoTLS is disabled: -``` -NAME URL LATEST AGE CONDITIONS READY REASON -autoscale-go http://autoscale-go.default.1.arenault.dev autoscale-go-dd42t 8m17s 3 OK / 3 True -``` + + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + annotations: + ... + networking.knative.dev/disable-auto-tls: "true" + ... + ``` + +1. The service URL should now be **http**, indicating that AutoTLS is disabled: + + ```bash + NAME URL LATEST AGE CONDITIONS READY REASON + autoscale-go http://autoscale-go.default.1.arenault.dev autoscale-go-dd42t 8m17s 3 OK / 3 True + ```