From 8773222d547394e70a7e94ca0811cbd6abff9b9f Mon Sep 17 00:00:00 2001 From: Reto Lehmann Date: Thu, 4 Jan 2024 09:05:20 +0100 Subject: [PATCH] Lint fixes, minor updates --- config/redirects.yml | 4 ++- .../serving/install-serving-with-yaml.md | 7 ++-- docs/serving/README.md | 4 +-- .../encryption/cluster-local-domain-tls.md | 2 ++ .../serving/encryption/encryption-overview.md | 10 +++--- .../serving/encryption/external-domain-tls.md | 4 +-- .../install-and-configure-net-certmanager.md | 32 +++++++++---------- .../serving/encryption/system-internal-tls.md | 2 ++ .../custom-tls-certificate-domain-mapping.md | 3 +- docs/serving/services/http-protocol.md | 3 +- docs/snippets/encryption-notice.md | 3 ++ 11 files changed, 43 insertions(+), 31 deletions(-) create mode 100644 docs/snippets/encryption-notice.md diff --git a/config/redirects.yml b/config/redirects.yml index e21b89f4d42..ae58e3cbaf0 100644 --- a/config/redirects.yml +++ b/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 diff --git a/docs/install/yaml-install/serving/install-serving-with-yaml.md b/docs/install/yaml-install/serving/install-serving-with-yaml.md index 2aac45d76a5..325397b0dfa 100644 --- a/docs/install/yaml-install/serving/install-serving-with-yaml.md +++ b/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 -=== "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. diff --git a/docs/serving/README.md b/docs/serving/README.md index 548f8ef4318..60e0f6f14fe 100644 --- a/docs/serving/README.md +++ b/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 diff --git a/docs/serving/encryption/cluster-local-domain-tls.md b/docs/serving/encryption/cluster-local-domain-tls.md index eb33329cc7c..f982db33164 100644 --- a/docs/serving/encryption/cluster-local-domain-tls.md +++ b/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: diff --git a/docs/serving/encryption/encryption-overview.md b/docs/serving/encryption/encryption-overview.md index f4e6ac618db..f2c4e640c60 100644 --- a/docs/serving/encryption/encryption-overview.md +++ b/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-.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. diff --git a/docs/serving/encryption/external-domain-tls.md b/docs/serving/encryption/external-domain-tls.md index 0840c7b7388..9e6c557efe0 100644 --- a/docs/serving/encryption/external-domain-tls.md +++ b/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` diff --git a/docs/serving/encryption/install-and-configure-net-certmanager.md b/docs/serving/encryption/install-and-configure-net-certmanager.md index fa90a13dcb9..9a49fbd77e5 100644 --- a/docs/serving/encryption/install-and-configure-net-certmanager.md +++ b/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.`, `myapp..svc` and `myapp..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-` (where is each namespace where Knative Services are created) +* `kn-user-` ( 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: diff --git a/docs/serving/encryption/system-internal-tls.md b/docs/serving/encryption/system-internal-tls.md index 369b3aa1a35..37f69a1ec81 100644 --- a/docs/serving/encryption/system-internal-tls.md +++ b/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: diff --git a/docs/serving/services/custom-tls-certificate-domain-mapping.md b/docs/serving/services/custom-tls-certificate-domain-mapping.md index 7811a7208e8..c13658f4dda 100644 --- a/docs/serving/services/custom-tls-certificate-domain-mapping.md +++ b/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 diff --git a/docs/serving/services/http-protocol.md b/docs/serving/services/http-protocol.md index 87d949f0901..8a951bddaed 100644 --- a/docs/serving/services/http-protocol.md +++ b/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 diff --git a/docs/snippets/encryption-notice.md b/docs/snippets/encryption-notice.md new file mode 100644 index 00000000000..35dda03b8e2 --- /dev/null +++ b/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!