[release-1.11] Document transport-encryption Eventing feature (#5655)

* Document transport-encryption feature Signed-off-by: Pierangelo Di Pilato <[email protected]> * Add verification and installation steps Signed-off-by: Pierangelo Di Pilato <[email protected]> * Add send event verification steps Signed-off-by: Pierangelo Di Pilato <[email protected]> * adding nav bar entry (#3) Signed-off-by: Matthias Wessendorf <[email protected]> --------- Signed-off-by: Pierangelo Di Pilato <[email protected]> Signed-off-by: Matthias Wessendorf <[email protected]> Co-authored-by: Pierangelo Di Pilato <[email protected]> Co-authored-by: Matthias Wessendorf <[email protected]>
knative · Aug 3, 2023 · c6a1a2d · c6a1a2d
1 parent ca55e40
commit c6a1a2d
Show file tree

Hide file tree

Showing 3 changed files with 305 additions and 7 deletions.
diff --git a/config/nav.yml b/config/nav.yml
@@ -280,6 +280,7 @@ nav:
         - KReference.Group field: eventing/experimental-features/kreference-group.md
         - Knative reference mapping: eventing/experimental-features/kreference-mapping.md
         - EventType auto creation: eventing/experimental-features/eventtype-auto-creation.md
+        - Transport Encryption: eventing/experimental-features/transport-encryption.md
     # Eventing reference docs
       - Reference:
         - Eventing API: eventing/reference/eventing-api.md

diff --git a/docs/eventing/experimental-features/README.md b/docs/eventing/experimental-features/README.md
@@ -67,10 +67,11 @@ data:
 The following table gives an overview of the available experimental features in
 Knative Eventing:
 
-| Feature | Flag | Description | Maturity |
-| ------- | ---- | ----------- | -------- |
-| [DeliverySpec.RetryAfterMax field](delivery-retryafter.md)  | `delivery-retryafter` | Specify a maximum retry duration that overrides HTTP [Retry-After](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3) headers when calculating backoff times for retrying **429** and **503** responses. | Alpha, disabled by default |
-| [DeliverySpec.Timeout field](delivery-timeout.md) | `delivery-timeout` | When using the `delivery` spec to configure event delivery parameters, you can use  the`timeout` field to specify the timeout for each sent HTTP request. | Alpha, disabled by default |
-| [KReference.Group field](kreference-group.md) | `kreference-group` | Specify the API `group` of `KReference` resources without the API version. | Alpha, disabled by default |
-| [Knative reference mapping](kreference-mapping.md) | `kreference-mapping` | Provide mappings from a [Knative reference](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#destination) to a templated URI. | Alpha, disabled by default |
-| [New trigger filters](new-trigger-filters.md) | `new-trigger-filters` | Enables a new Trigger `filters` field that supports a set of powerful filter expressions. | Alpha, disabled by default |
+| Feature                                                    | Flag                   | Description                                                                                                                                                                                                        | Maturity |
+|------------------------------------------------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+| [DeliverySpec.RetryAfterMax field](delivery-retryafter.md) | `delivery-retryafter`  | Specify a maximum retry duration that overrides HTTP [Retry-After](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3) headers when calculating backoff times for retrying **429** and **503** responses. | Alpha, disabled by default |
+| [DeliverySpec.Timeout field](delivery-timeout.md)          | `delivery-timeout`     | When using the `delivery` spec to configure event delivery parameters, you can use  the`timeout` field to specify the timeout for each sent HTTP request.                                                          | Alpha, disabled by default |
+| [KReference.Group field](kreference-group.md)              | `kreference-group`     | Specify the API `group` of `KReference` resources without the API version.                                                                                                                                         | Alpha, disabled by default |
+| [Knative reference mapping](kreference-mapping.md)         | `kreference-mapping`   | Provide mappings from a [Knative reference](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#destination) to a templated URI.                                                                 | Alpha, disabled by default |
+| [New trigger filters](new-trigger-filters.md)              | `new-trigger-filters`  | Enables a new Trigger `filters` field that supports a set of powerful filter expressions.                                                                                                                          | Alpha, disabled by default |
+| [Transport encryption](transport-encryption.md)            | `transport-encryption` | Enables components to encrypt traffic using TLS by exposing HTTPS URL.                                                                                                                                             | Alpha, disabled by default |
diff --git a/docs/eventing/experimental-features/transport-encryption.md b/docs/eventing/experimental-features/transport-encryption.md
@@ -0,0 +1,296 @@
+# Transport Encryption for Knative Eventing
+
+**Flag name**: `transport-encryption`
+
+**Stage**: Alpha, disabled by default
+
+**Tracking issue**: [#5957](https://github.com/knative/eventing/issues/5957)
+
+## Overview
+
+By default, event delivery within the cluster is unencrypted. This limits the types of events which
+can be transmitted to those of low compliance value (or a relaxed compliance posture)
+or, alternatively, forces administrators to use a service mesh or encrypted CNI to encrypt the
+traffic, which poses many challenges to Knative Eventing adopters.
+
+Knative Brokers and Channels provides HTTPS endpoints to receive events. Given that these
+endpoints typically do not have public DNS names (e.g. svc.cluster.local or the like), these need to
+be signed by a non-public CA (cluster or organization specific CA).
+
+Event producers are be able to connect to HTTPS endpoints with cluster-internal CA certificates.
+
+## Prerequisites
+
+- In order to enable the transport encryption feature, you will need to install cert-manager
+  operator by
+  following [the cert-manager operator installation instructions](https://cert-manager.io/docs/installation/).
+- [Eventing installation](./../../install)
+
+## Installation
+
+Eventing components use cert-manager issuers and certificates to provision TLS certificates and in
+the release assets, we release such default issuers and certificates that can be customized as
+necessary.
+
+1. Install issuers and certificates, run the following command:
+    ```shell
+    kubectl apply -f {{ artifact(repo="eventing",file="eventing-tls-networking.yaml")}}
+    ```
+2. Verify issuers and certificates are ready
+    ```shell
+    kubectl get certificates.cert-manager.io -n knative-eventing
+    ```
+   Example output:
+    ```shell
+    NAME                           READY   SECRET                         AGE
+    imc-dispatcher-server-tls      True    imc-dispatcher-server-tls      14s
+    mt-broker-filter-server-tls    True    mt-broker-filter-server-tls    14s
+    mt-broker-ingress-server-tls   True    mt-broker-ingress-server-tls   14s
+    selfsigned-ca                  True    eventing-ca                    14s
+    ```
+
+## Transport Encryption configuration
+
+The `transport-encryption` feature flag is an enum configuration that configures how Addressables (
+Broker, Channel, Sink) should accept events.
+
+The possible values for `transport-encryption` are:
+
+- `disabled` (this is equivalent to the current behavior)
+    - Addressables may accept events to HTTPS endpoints
+    - Producers may send events to HTTPS endpoints
+- `permissive`
+    - Addressables should accept events on both HTTP and HTTPS endpoints
+    - Addressables should advertise both HTTP and HTTPS endpoints
+    - Producers should prefer sending events to HTTPS endpoints, if available
+- `strict`
+    - Addressables must not accept events to non-HTTPS endpoints
+    - Addressables must only advertise HTTPS endpoints
+
+For example, to enable `strict` transport encryption, the `config-features` ConfigMap will look like
+the following:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: config-features
+  namespace: knative-eventing
+data:
+  transport-encryption: "strict"
+```
+
+## Verifying that the feature is working
+
+Save the following YAML into a file called `default-broker-example.yaml`
+
+```yaml
+# default-broker-example.yaml
+
+apiVersion: eventing.knative.dev/v1
+kind: Broker
+metadata:
+  name: br
+
+---
+apiVersion: eventing.knative.dev/v1
+kind: Trigger
+metadata:
+  name: tr
+spec:
+  broker: br
+  subscriber:
+    ref:
+      apiVersion: v1
+      kind: Service
+      name: event-display
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: event-display
+spec:
+  selector:
+    app: event-display
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 8080
+---
+apiVersion: v1
+kind: Pod
+metadata:
+  name: event-display
+  labels:
+    app: event-display
+spec:
+  containers:
+    - name: event-display
+      image: gcr.io/knative-releases/knative.dev/eventing/cmd/event_display
+      imagePullPolicy: Always
+      ports:
+        - containerPort: 8080
+```
+
+Apply the `default-broker-example.yaml` file into a test namespace  `transport-encryption-test`:
+
+```shell
+kubectl create namespace transport-encryption-test
+
+kubectl apply -n transport-encryption-test -f defautl-broker-example.yaml
+```
+
+Verify that addresses are all `HTTPS`:
+```shell
+kubectl get brokers.eventing.knative.dev -n transport-encryption-test br -oyaml
+```
+
+Example output:
+
+```shell
+apiVersion: eventing.knative.dev/v1
+kind: Broker
+metadata:
+  # ...
+  name: br
+  namespace: transport-encryption-test
+# ...
+status:
+  address:
+    CACerts: |
+      -----BEGIN CERTIFICATE-----
+      MIIBbzCCARagAwIBAgIQAur7vdEcreEWSEQatCYlNjAKBggqhkjOPQQDAjAYMRYw
+      FAYDVQQDEw1zZWxmc2lnbmVkLWNhMB4XDTIzMDgwMzA4MzA1N1oXDTIzMTEwMTA4
+      MzA1N1owGDEWMBQGA1UEAxMNc2VsZnNpZ25lZC1jYTBZMBMGByqGSM49AgEGCCqG
+      SM49AwEHA0IABBqkD9lAwrnXCo/OOdpKzJROSbzCeC73FE/Np+/j8n862Ox5xYwJ
+      tAp/o3RDpDa3omhzqZoYumqdtneozGFY/zGjQjBAMA4GA1UdDwEB/wQEAwICpDAP
+      BgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBSHoKjXzfxfudt3mVGU3VudSi6TrTAK
+      BggqhkjOPQQDAgNHADBEAiA5z0/TpD7T6vRpN9VQisQMtum/Zg3tThnYA5nFnAW7
+      KAIgKR/EzW7f8BPcnlcgXt5kp3Fdqye1SAkjxZzr2a0Zik8=
+      -----END CERTIFICATE-----
+    name: https
+    url: https://broker-ingress.knative-eventing.svc.cluster.local/transport-encryption-test/br
+  addresses:
+  - CACerts: |
+      -----BEGIN CERTIFICATE-----
+      MIIBbzCCARagAwIBAgIQAur7vdEcreEWSEQatCYlNjAKBggqhkjOPQQDAjAYMRYw
+      FAYDVQQDEw1zZWxmc2lnbmVkLWNhMB4XDTIzMDgwMzA4MzA1N1oXDTIzMTEwMTA4
+      MzA1N1owGDEWMBQGA1UEAxMNc2VsZnNpZ25lZC1jYTBZMBMGByqGSM49AgEGCCqG
+      SM49AwEHA0IABBqkD9lAwrnXCo/OOdpKzJROSbzCeC73FE/Np+/j8n862Ox5xYwJ
+      tAp/o3RDpDa3omhzqZoYumqdtneozGFY/zGjQjBAMA4GA1UdDwEB/wQEAwICpDAP
+      BgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBSHoKjXzfxfudt3mVGU3VudSi6TrTAK
+      BggqhkjOPQQDAgNHADBEAiA5z0/TpD7T6vRpN9VQisQMtum/Zg3tThnYA5nFnAW7
+      KAIgKR/EzW7f8BPcnlcgXt5kp3Fdqye1SAkjxZzr2a0Zik8=
+      -----END CERTIFICATE-----
+    name: https
+    url: https://broker-ingress.knative-eventing.svc.cluster.local/transport-encryption-test/br
+  annotations:
+    knative.dev/channelAPIVersion: messaging.knative.dev/v1
+    knative.dev/channelAddress: https://imc-dispatcher.knative-eventing.svc.cluster.local/transport-encryption-test/br-kne-trigger
+    knative.dev/channelCACerts: |
+      -----BEGIN CERTIFICATE-----
+      MIIBbzCCARagAwIBAgIQAur7vdEcreEWSEQatCYlNjAKBggqhkjOPQQDAjAYMRYw
+      FAYDVQQDEw1zZWxmc2lnbmVkLWNhMB4XDTIzMDgwMzA4MzA1N1oXDTIzMTEwMTA4
+      MzA1N1owGDEWMBQGA1UEAxMNc2VsZnNpZ25lZC1jYTBZMBMGByqGSM49AgEGCCqG
+      SM49AwEHA0IABBqkD9lAwrnXCo/OOdpKzJROSbzCeC73FE/Np+/j8n862Ox5xYwJ
+      tAp/o3RDpDa3omhzqZoYumqdtneozGFY/zGjQjBAMA4GA1UdDwEB/wQEAwICpDAP
+      BgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBSHoKjXzfxfudt3mVGU3VudSi6TrTAK
+      BggqhkjOPQQDAgNHADBEAiA5z0/TpD7T6vRpN9VQisQMtum/Zg3tThnYA5nFnAW7
+      KAIgKR/EzW7f8BPcnlcgXt5kp3Fdqye1SAkjxZzr2a0Zik8=
+      -----END CERTIFICATE-----
+    knative.dev/channelKind: InMemoryChannel
+    knative.dev/channelName: br-kne-trigger
+  conditions:
+  # ...
+```
+
+Sending events to the Broker using HTTPS endpoints:
+
+```shell
+kubectl run curl -n transport-encryption-test --image=curlimages/curl -i --tty -- sh
+
+```
+
+Save the CA certs from the Broker's `.status.address.CACerts` field into `/tmp/cacerts.pem`
+
+```shell
+cat <<EOF >> /tmp/cacerts.pem
+-----BEGIN CERTIFICATE-----
+MIIBbzCCARagAwIBAgIQAur7vdEcreEWSEQatCYlNjAKBggqhkjOPQQDAjAYMRYw
+FAYDVQQDEw1zZWxmc2lnbmVkLWNhMB4XDTIzMDgwMzA4MzA1N1oXDTIzMTEwMTA4
+MzA1N1owGDEWMBQGA1UEAxMNc2VsZnNpZ25lZC1jYTBZMBMGByqGSM49AgEGCCqG
+SM49AwEHA0IABBqkD9lAwrnXCo/OOdpKzJROSbzCeC73FE/Np+/j8n862Ox5xYwJ
+tAp/o3RDpDa3omhzqZoYumqdtneozGFY/zGjQjBAMA4GA1UdDwEB/wQEAwICpDAP
+BgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBSHoKjXzfxfudt3mVGU3VudSi6TrTAK
+BggqhkjOPQQDAgNHADBEAiA5z0/TpD7T6vRpN9VQisQMtum/Zg3tThnYA5nFnAW7
+KAIgKR/EzW7f8BPcnlcgXt5kp3Fdqye1SAkjxZzr2a0Zik8=
+-----END CERTIFICATE-----
+EOF
+```
+
+Send the event by running the following command:
+
+```shell
+curl -v -X POST -H "content-type: application/json" -H "ce-specversion: 1.0" -H "ce-source: my/curl/command" -H "ce-type: my.demo.event" -H "ce-id: 6cf17c7b-30b1-45a6-80b0-4cf58c92b947" -d '{"name":"Knative Demo"}' --cacert /tmp/cacert
+s.pem https://broker-ingress.knative-eventing.svc.cluster.local/transport-encryption-test/br
+```
+
+Example output:
+
+```shell
+* processing: https://broker-ingress.knative-eventing.svc.cluster.local/transport-encryption-test/br
+*   Trying 10.96.174.249:443...
+* Connected to broker-ingress.knative-eventing.svc.cluster.local (10.96.174.249) port 443
+* ALPN: offers h2,http/1.1
+* TLSv1.3 (OUT), TLS handshake, Client hello (1):
+*  CAfile: /tmp/cacerts.pem
+*  CApath: none
+* TLSv1.3 (IN), TLS handshake, Server hello (2):
+* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
+* TLSv1.3 (IN), TLS handshake, Certificate (11):
+* TLSv1.3 (IN), TLS handshake, CERT verify (15):
+* TLSv1.3 (IN), TLS handshake, Finished (20):
+* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
+* TLSv1.3 (OUT), TLS handshake, Finished (20):
+* SSL connection using TLSv1.3 / TLS_AES_128_GCM_SHA256
+* ALPN: server accepted h2
+* Server certificate:
+*  subject: O=local
+*  start date: Aug  3 08:31:02 2023 GMT
+*  expire date: Nov  1 08:31:02 2023 GMT
+*  subjectAltName: host "broker-ingress.knative-eventing.svc.cluster.local" matched cert's "broker-ingress.knative-eventing.svc.cluster.local"
+*  issuer: CN=selfsigned-ca
+*  SSL certificate verify ok.
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* using HTTP/2
+* h2 [:method: POST]
+* h2 [:scheme: https]
+* h2 [:authority: broker-ingress.knative-eventing.svc.cluster.local]
+* h2 [:path: /transport-encryption-test/br]
+* h2 [user-agent: curl/8.2.1]
+* h2 [accept: */*]
+* h2 [content-type: application/json]
+* h2 [ce-specversion: 1.0]
+* h2 [ce-source: my/curl/command]
+* h2 [ce-type: my.demo.event]
+* h2 [ce-id: 6cf17c7b-30b1-45a6-80b0-4cf58c92b947]
+* h2 [content-length: 23]
+* Using Stream ID: 1
+> POST /transport-encryption-test/br HTTP/2
+> Host: broker-ingress.knative-eventing.svc.cluster.local
+> User-Agent: curl/8.2.1
+> Accept: */*
+> content-type: application/json
+> ce-specversion: 1.0
+> ce-source: my/curl/command
+> ce-type: my.demo.event
+> ce-id: 6cf17c7b-30b1-45a6-80b0-4cf58c92b947
+> Content-Length: 23
+> 
+< HTTP/2 202 
+< allow: POST, OPTIONS
+< content-length: 0
+< date: Thu, 03 Aug 2023 10:08:22 GMT
+< 
+* Connection #0 to host broker-ingress.knative-eventing.svc.cluster.local left intact
+```