Lint fixes, minor updates

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
       about/case-studies/README.md: about/case-studies/deepc.md
       eventing/brokers/create-mtbroker.md: eventing/brokers/create-broker.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

@@ -1,5 +1,7 @@
 # Configure cluster-local domain encryption
 
+{% include "encryption-notice.md" %}
+
 ## Before you begin
 
 You must meet the following requirements to enable secure HTTPS connections:

docs/serving/encryption/encryption-overview.md

@@ -1,5 +1,7 @@
 # Serving Encryption Overview
 
+{% include "encryption-notice.md" %}
+
 There are three parts to Knative Serving encryption:
 
 1. HTTPS on the ingress layer _external_ to the cluster (cluster external domain, like `myapp-<namespace>.example.com`).
@@ -9,10 +11,10 @@ There are three parts to Knative Serving encryption:
 ![Overview of Knative encryption](./encryption-overview.drawio.svg)
 
 !!! note
-    Currently, all control-plane traffic (including Kubernetes PreStopHooks and metadata like metrics) are not encrypted.
+    Currently, all control-plane traffic (including Kubernetes PreStopHooks and metadata like metrics) is not encrypted.
 
 ## The parts in detail
-The different parts are independent of each other and (can) use different Certificate Authorities to sign the necessary certificates.
+The different parts are independent of each other and (can) use different Certificate Authorities to sign certificates.
 
 ### External domain encryption
 
@@ -29,7 +31,7 @@ See [Configure external domain encryption](./external-domain-tls.md) for more in
 
 ![Cluster local domain](./encryption-cluster-local-domain.drawio.svg)
 
-* Certificate CN/SAN contains the cluster-local domain of a Knative Service, e.g. `myapp.namespace.svc.cluster.local`, `myapp.namespace.svc`, `myapp.namespace`.
+* Certificate CN/SAN contains the cluster-local domains of a Knative Service, e.g. `myapp.namespace.svc.cluster.local`, `myapp.namespace.svc`, `myapp.namespace`.
 * The certificates are hosted using SNI by the cluster-local endpoint of the ingress-controller.
 * The caller has to trust the CA that signed the certificates (this is out of the scope of Knative). One option to do this is using [trust-manager](https://cert-manager.io/docs/trust/trust-manager/) from cert-manager.
 * To create the certificates, Knative relies on [cert-manager](https://cert-manager.io/) and our bridging component [net-certmanager](https://github.com/knative-extensions/net-certmanager/). They need to be installed and configured for the feature to work.
@@ -40,7 +42,7 @@ See [Configure cluster-local domain encryption](./cluster-local-domain-tls.md) f
 
 ![Knative system internal](./encryption-system-internal.drawio.svg)
 
-Knative system internal components (`ingress-controller`, `activator`, `queue-proxy`) are hosting TLS endpoints when this configuration is enabled.
+Knative system internal components (Ingress-Controller, Activator, Queue-Proxy) are hosting TLS endpoints when this configuration is enabled.
 
 * To get the certificates, Knative relies on [cert-manager](https://cert-manager.io/) and our bridging component [net-certmanager](https://github.com/knative-extensions/net-certmanager/). They need to be installed and configured for the feature to work.
 * Specific SANs are used to verify each connection. Each component needs to trust the CA (possibly the full chain) that signed the certificates. For this, Knative system components will consume and trust a provided `CABundle`. The CA bundle needs to be provided by the cluster administrator, possibly using [trust-manager](https://cert-manager.io/docs/trust/trust-manager/) from cert-manager.

docs/serving/encryption/external-domain-tls.md

@@ -41,7 +41,7 @@ Only one of them can be active at the same time!
 
 #### Using a certificate for each Knative Service
 
-Update the [`config-network` ConfigMap](https://github.com/knative/serving/blob/main/config/core/configmaps/network.yaml) in the `knative-serving` namespace to enable `external-domain-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 `external-domain-tls`:
 
 1.  Run the following command to edit your `config-network` ConfigMap:
 
@@ -67,7 +67,7 @@ Update the [`config-network` ConfigMap](https://github.com/knative/serving/blob/
 
 !!! warning
     Provisioning a wildcard Certificate per namespace only works with DNS-01
-    challenge. This component cannot be used with HTTP-01 challenge.
+    challenge. This feature cannot be used with HTTP-01 challenge.
 
 The per-namespace configuration uses namespace labels to select which namespaces should have a 
 certificate applied. The selection is configured using the key `namespace-wildcard-cert-selector`

docs/serving/encryption/install-and-configure-net-certmanager.md

@@ -20,8 +20,8 @@ kubectl apply -f {{ artifact( repo="net-certmanager", file="release.yaml") }}
 ```
 
 !!! warning
-    Knative, per default, installs a self-signed cert-manager `ClusterIssuer` for an easy quick-start. 
-    This issuer should **NOT BE USED IN PRODUCTION**! You can add a label filter to the command above, 
+    Per default, this installs a self-signed cert-manager `ClusterIssuer` for an easy quick-start. 
+    This issuer should **NOT BE USED IN PRODUCTION**! You can add a label filter to the command above 
     to remove the issuer from the installation and configure your issuer manually: `--selector knative.dev/issuer-install!="true"`
 
 Installing net-certmanager using the Knative operator is not yet supported. 
@@ -39,9 +39,9 @@ for the [three Knative Serving encryption features](./encryption-overview.md):
 * `systemInternalIssuerRef`: issuer for certificates for system-internal-tls certificates used by Knative internal components.
 
 Per default, Knative uses a self-signed `ClusterIssuer` and net-certmanager references that `ClusterIssuer` for all three configurations.
-As this **should not be used in production**, you should think about which CA should be used for each use-case and 
-how trust will be distributed to the clients calling the encrypted services. For the Knative system components, Knative provides 
-a way to specify a bundle of CAs that should be trusted (more on this below).
+As this **should not be used in production** (and does not support rotating the CA without downtime),
+you should think about which CA should be used for each use-case and how trust will be distributed to the clients calling the encrypted services. 
+For the Knative system components, Knative provides a way to specify a bundle of CAs that should be trusted (more on this below).
 
 There is no general answer on how to structure this, here an example on how it could look like:
 
@@ -57,7 +57,7 @@ There is no general answer on how to structure this, here an example on how it c
 In general, you can refer to the [cert-manager documentation](https://cert-manager.io/docs/configuration/acme/#creating-a-basic-acme-issuer). There are examples available for:
 
 * [CA based on a K8s secret](https://cert-manager.io/docs/configuration/ca/)
-* [Let's encrypt](https://cert-manager.io/docs/configuration/acme/#creating-a-basic-acme-issuer)
+* [HTTP-01 challenges, e.g. Let's encrypt](https://cert-manager.io/docs/configuration/acme/#creating-a-basic-acme-issuer)
 * [DNS-01 challenges](https://cert-manager.io/docs/configuration/acme/dns01/)
 * [Self-signed issuers](https://cert-manager.io/docs/configuration/selfsigned/)
 
@@ -67,10 +67,10 @@ In general, you can refer to the [cert-manager documentation](https://cert-manag
 `cluster-local-domain-tls` needs to be able to sign certificates for cluster-local domains like `myapp.<namespace>`, `myapp.<namespace>.svc` and `myapp.<namespace>.svc.cluster.local`. 
 As the CA usually is not within the cluster, verification via ACME protocol (DNS01/HTTP01) is not possible. You can use an issuer that allows creating the these certificates (e.g. CA issuer).
 
-`system-internal-tls` needs to be able to sign specific SANs that Knative validates for. As these kn-routingcomponents are not strictly routable, the defined set of SANs is:
+`system-internal-tls` needs to be able to sign specific SANs that Knative validates for. The defined set of SANs is:
 
 * `kn-routing`
-* `kn-user-<namespace>` (where <namespace> is each namespace where Knative Services are created)
+* `kn-user-<namespace>` (<namespace> is each namespace where Knative Services are/will be created)
 * `data-plane.knative.dev`
 
 As this is also not possible via ACME protocol (DNS01/HTTP01), you need to configure an issuer that allows creating the these certificates (e.g. CA issuer).
@@ -139,15 +139,15 @@ trust needs to be distributed:
 
 ### Trusting for cluster internal clients (e.g. Knative or Vanilla K8s workload)
 
-As we do not control all your workload and the settings are highly dependent on your runtime and/or language, this is out of scope of Knative.
-But here a few points to consider. There are several ways on how to provide CAs to your application:
+As Knative does not control all workload and the settings are highly dependent on your runtime and/or language, this is out of scope of Knative.
+But here a few points to consider, as there are several ways on how to provide CAs to your application:
 
-* Adding the CA bundle to a Container image on build-time (be aware that this causes more strain on CA rotation)
+* Adding the CA bundle to a Container image on build-time (be aware that this complicates CA rotation, you basically need to rebuild every application)
 * Mounting a CA bundle to the filesystem (e.g. from a `Secret` or `ConfigMap`)
 * Reading it from environment variable
 * Accessing it from a `Secret`/`ConfigMap` via K8s API
 
-Important is to decide if a reload without downtime is necessary, if so the workload must either watch changes on the K8s resource or watch the filesystem. For the latter it is important, that `ionotify` on changing Secrets/ConfigMaps does not work super reliable on K8s. Tests showed that it is more reliable to regularly poll and check the certificate on the filesystem for changes.
+Important is to decide if a reload without downtime is necessary, if yes, the workload must either watch changes on the K8s resource or watch the filesystem. For the latter it is important, that `ionotify` on changing Secrets/ConfigMaps does not work super reliable on K8s. Tests showed that it is more reliable to regularly poll and check the certificate on the filesystem for changes.
 
 Here are a few examples for golang:
 
@@ -158,7 +158,7 @@ Here are a few examples for golang:
 
 ### Trusting for Knative system components
 
-Knative system components can be configured to trust one or many CA bundles from `ConfigMaps`. The cluster operator needs to make sure,
+Knative system components can be configured to trust one or many CA bundles from `ConfigMaps`. The cluster operator needs to ensure,
 to configure them accordingly to avoid any downtimes [during a rotation](#trust-during-rotation). Knative components look for a `ConfigMap`
 in the namespace where the component runs, e.g:
 
@@ -167,8 +167,8 @@ in the namespace where the component runs, e.g:
 * kourier-system (when using net-kourier)
 * Each namespace where a Knative Service runs
 
-Knative looks for a `ConfigMap` with the label `knative-ca-trust-bundle="true"` and will read all keys. One key can contain one or multiple CAs/Intermediates. 
-If they are valid, they will be added to the trust store of the Knative components.
+Knative looks for a `ConfigMap` with the label `knative-ca-trust-bundle="true"` and will read all `data` keys (regardless of the name). 
+One key can contain one or multiple CAs/Intermediates. If they are valid, they will be added to the trust store of the Knative components.
 
 Here is an example of how `ConfigMap` could look like:
 
@@ -211,7 +211,7 @@ to automatically distribute the CA bundles. Please refer to their documentation
 
 ### Trust during rotation
 
-During a rotation of a CA and/or Intermediate certificates your clients will need to trust the old and the new chain until the
+During a rotation of a CA and/or Intermediate certificates your clients will need to trust the old and the new CA/chain until the
 rotation is done. Using the [trust approach](#managing-trust-and-rotation-without-downtime) from above, you can do a full
 chain rotation without downtime:
 

docs/serving/encryption/system-internal-tls.md

@@ -1,5 +1,7 @@
 # Configure Knative system-internal encryption
 
+{% include "encryption-notice.md" %}
+
 ## Before you begin
 
 You must meet the following requirements to enable secure HTTPS connections:

docs/serving/services/custom-tls-certificate-domain-mapping.md

@@ -4,7 +4,8 @@
 
 By providing the reference to an existing _TLS Certificate_ you can instruct a `DomainMapping` to use that
 certificate to secure the mapped service. 
-Please note that for Services using this feature, the automatic certificate creation using [external-domain-tls](../encryption/enabling-automatic-tls-certificate-provisioning.md) is skipped.
+Please note that for Services using this feature, the automatic certificate creation using 
+[external-domain-tls](../encryption/external-domain-tls.md) is skipped.
 
 ## Prerequisites
 

docs/serving/services/http-protocol.md

@@ -1,6 +1,7 @@
 # HTTPS redirection
 
-Operators can force HTTPS redirection for all Services. See the `http-protocol` mentioned in the [Enabling automatic TLS certificate provisioning](../encryption/enabling-automatic-tls-certificate-provisioning.md) page for more details.
+Operators can force HTTPS redirection for all Services. See the `http-protocol` mentioned in
+[Configure external domain encryption](../encryption/external-domain-tls.md) page for more details.
 
 ## Overriding the default HTTP behavior
 

docs/snippets/encryption-notice.md

@@ -0,0 +1,3 @@
+!!! warning
+    The Knative Serving encryption features `cluster-local-domain-tls` and `system-internal-tls` are in experimental state.
+    Please use with caution!