Add documentation for Serving Encryption

config/nav.yml

@@ -158,8 +158,11 @@ nav:
           - Feature and extension flags: serving/configuration/feature-flags.md
           - Configure the Defaults ConfigMap: serving/configuration/config-defaults.md
         - Serving encryption configuration:
-          - Using custom TLS certificates in the networking layer: serving/encryption/using-certificates-in-networking-layer.md
-          - Enabling automatic TLS certificate provisioning: serving/encryption/enabling-automatic-tls-certificate-provisioning.md
+          - Overview: serving/encryption/encryption-overview.md
+          - Configure cert-manager integration: serving/encryption/configure-certmanager-integration.md
+          - Configure external domain encryption: serving/encryption/external-domain-tls.md
+          - Configure cluster-local domain encryption: serving/encryption/cluster-local-domain-tls.md
+          - Configure Knative system-internal encryption: serving/encryption/system-internal-tls.md
       # Serving - Application Security
       - Application security:
         - About Security-Guard: serving/app-security/security-guard-about.md

config/redirects.yml

@@ -208,7 +208,9 @@ plugins:
       serving/services/deployment.md: serving/configuration/deployment.md
       serving/services/http-option.md: serving/services/http-protocol.md
       serving/spec/knative-api-specification-1.0.md: https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md
-      serving/using-an-ssl-cert/index.md: serving/encryption/using-certificates-in-networking-layer.md
+      serving/using-an-ssl-cert/index.md: serving/encryption/encryption-overview.md
+      serving/encryption/enabling-automatic-tls-certificate-provisioning.md: serving/encryption/encryption-overview.md
+      serving/encryption/using-certificates-in-networking-layer.md: serving/encryption/encryption-overview.md
       serving/using-subroutes.md: serving/traffic-management.md
       eventing/brokers/create-mtbroker.md: eventing/brokers/create-broker.md
       eventing/brokers/broker-admin-config-options.md: eventing/configuration/broker-configuration.md

docs/install/installing-cert-manager.md

@@ -1,42 +1,22 @@
 # Installing cert-manager for TLS certificates
 
-Install the [Cert-Manager](https://github.com/jetstack/cert-manager) tool to
-obtain TLS certificates that you can use for secure HTTPS connections in
-Knative. For more information about enabling HTTPS connections in Knative, see
-[Using custom certificates in networking-layer](../serving/encryption/using-certificates-in-networking-layer.md).
-
-You can use cert-manager to either manually obtain certificates, or to enable
-Knative for automatic certificate provisioning. Complete instructions about this are provided in
-[Enabling automatic TLS certificate provisioning](../serving/encryption/enabling-automatic-tls-certificate-provisioning.md).
-
-Regardless of if your want to manually obtain certificates, or configure Knative
-for automatic provisioning, you can use the following steps to install
-cert-manager.
+Knative leverages [cert-manager](https://github.com/jetstack/cert-manager) to request TLS certificates
+used for secure HTTPS connections in Knative. Installing [cert-manager](https://github.com/jetstack/cert-manager)
+is required before enabling any of the Knative encryption features. Follow the steps below for the installation.
 
 ## Before you begin
 
 You must meet the following requirements to install cert-manager for Knative:
 
-- Knative Serving must be installed. For details about installing the Serving
-  component, see the [Knative installation guide](yaml-install/serving/install-serving-with-yaml.md).
-- You must configure your Knative cluster to use a
-  [custom domain](../serving/using-a-custom-domain.md).
 - Knative currently supports cert-manager version `1.0.0` and higher.
 
 ## Downloading and installing cert-manager
 
-To download and install cert-manager, follow the [Installation steps](https://cert-manager.io/docs/installation/kubernetes/) from the official `cert-manager` website.
+To download and install cert-manager, follow the [Installation steps](https://cert-manager.io/docs/installation/) from the official `cert-manager` website.
 
-## Completing the Knative configuration for TLS support
+## Using cert-manager with Knative
 
-Before you can use a TLS certificate for secure connections, you must finish
-configuring Knative:
+Knative encryption can be configured in:
 
-- **Manual**: If you installed cert-manager to manually obtain certificates,
-  continue to the following topic for instructions about creating a Kubernetes
-  secret:
-  [Manually adding a TLS certificate](../serving/encryption/using-certificates-in-networking-layer.md#manually-adding-a-tls-certificate)
+* [Serving: Encryption Overview](../serving/encryption/encryption-overview.md)
 
-- **Automatic**: If you installed cert-manager to use for automatic certificate
-  provisioning, continue to the following topic to enable that feature:
-  [Enabling automatic TLS certificate provisioning](../serving/encryption/enabling-automatic-tls-certificate-provisioning.md)

docs/install/yaml-install/serving/install-serving-with-yaml.md

@@ -167,9 +167,8 @@ The following tabs expand to show instructions for installing each Serving exten
 
     <!-- TODO(https://github.com/knative/docs/issues/2152): Link to a more in-depth guide on HPA-class autoscaling -->
 
-=== "TLS with cert-manager"
+=== "Knative encryption with cert-manager"
 
-    Knative supports automatically provisioning TLS certificates through
-    [cert-manager](https://cert-manager.io/docs/).
-    Follow the documentation in [Enabling automatic TLS certificate provisioning](../../../serving/encryption/enabling-automatic-tls-certificate-provisioning.md)
+    Knative supports encryption features through  [cert-manager](https://cert-manager.io/docs/).
+    Follow the documentation in [Serving encryption](../../../serving/encryption/encryption-overview.md)
     for more information.

docs/serving/README.md

@@ -10,7 +10,7 @@ Examples of supported Knative Serving use cases:
 - Autoscaling, including scaling pods down to zero.
 - Support for multiple networking layers, such as Contour, Kourier, and Istio, for integration into existing environments.
 
-Knative Serving supports both HTTP and [HTTPS](encryption/using-certificates-in-networking-layer.md) networking protocols.
+Knative Serving supports both HTTP and [HTTPS](encryption/encryption-overview.md) networking protocols.
 
 ## Installation
 
@@ -19,7 +19,7 @@ You can install Knative Serving via the methods listed on the [installation page
 ## Getting Started
 
 To get started with Serving, check out one of the [hello world](../samples/serving.md)
-sample projects. These projects use the `Service` resource, which manages all of
+sample projects. These projects use the `Service` resource, which manages all
 the details for you.
 
 With the `Service` resource, a deployed service will automatically have a

docs/serving/encryption/cluster-local-domain-tls.md

@@ -0,0 +1,88 @@
+# Configure cluster-local domain encryption
+
+{% include "encryption-notice.md" %}
+
+## Before you begin
+
+You must meet the following requirements to enable secure HTTPS connections:
+
+- Knative Serving must be installed. For details about installing the Serving
+  component, see the [Knative installation guides](../../install/yaml-install/serving/install-serving-with-yaml.md).
+
+!!! warning
+    This feature is currently only supported with Kourier and Istio as a networking layer.
+
+
+## Installing and configuring cert-manager and integration
+
+First, you need to install and configure `cert-manager` and the Knative cert-manager integration.
+Please refer to [Configuring Knative cert-manager integration](./configure-certmanager-integration.md) for details.
+
+
+## Enabling cluster-local-domain-tls
+
+To enable `cluster-local-domain-tls` update the [`config-network` ConfigMap](https://github.com/knative/serving/blob/main/config/core/configmaps/network.yaml) in the `knative-serving` namespace:
+
+1.  Run the following command to edit your `config-network` ConfigMap:
+
+    ```bash
+    kubectl edit configmap config-network -n knative-serving
+    ```
+
+1.  Add the `cluster-local-domain-tls: Enabled` attribute under the `data` section:
+
+    ```yaml
+    apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: config-network
+      namespace: knative-serving
+    data:
+       ...
+       cluster-local-domain-tls: Enabled
+       ...
+    ```
+
+1. Restart the Knative Serving controller to start the Knative cert-manager integration:
+
+    ```bash
+    kubectl rollout restart deploy/controller -n knative-serving
+    ```
+
+Congratulations! Knative is now configured to obtain and renew TLS certificates for cluster-local domains.
+
+
+## Verification
+
+1. Deploy a Knative Service
+
+1. Check the URL with `kubectl get ksvc -n <your-namespace> -o yaml`
+
+1. The service URL cluster-local domain (https://helloworld.test.svc.cluster.local) should now be **https**:
+
+```yaml
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: helloworld
+  namespace: test
+spec:
+  # ...
+status:
+  address:
+    # cluster-local-domain:
+    url: https://helloworld.test.svc.cluster.local
+  # ...
+  # external domain:
+  url: http://helloworld.first.example.com
+```
+
+
+## Trust
+
+!!! note
+    A quick note on trust, all clients that call the cluster-local domain of a Knative Service need to trust the Certificate Authority
+    that signed the certificates. This is out of scope of Knative, but needs to be addressed to ensure a working system. Especially,
+    when a Certificate Authority performs a rotation of the CA or the intermediate certificates. Find more information on
+    [Configuring Knative cert-manager integration](./configure-certmanager-integration.md#managing-trust-and-rotation-without-downtime).
+