From 08fb4921c77667bba18803542a819ee636d7cad1 Mon Sep 17 00:00:00 2001 From: Pierangelo Di Pilato Date: Fri, 28 Jul 2023 16:16:46 +0200 Subject: [PATCH 1/4] Document transport-encryption feature Signed-off-by: Pierangelo Di Pilato --- docs/eventing/experimental-features/README.md | 15 ++--- .../transport-encryption.md | 62 +++++++++++++++++++ 2 files changed, 70 insertions(+), 7 deletions(-) create mode 100644 docs/eventing/experimental-features/transport-encryption.md diff --git a/docs/eventing/experimental-features/README.md b/docs/eventing/experimental-features/README.md index 926e84ca5a..de03f594be 100644 --- 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 new file mode 100644 index 0000000000..8a76af784d --- /dev/null +++ b/docs/eventing/experimental-features/transport-encryption.md @@ -0,0 +1,62 @@ +# 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/). + +## 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 + +// TODO + From a3f061f6e26719d96101f0d56544c1bb594c1d12 Mon Sep 17 00:00:00 2001 From: Pierangelo Di Pilato Date: Thu, 3 Aug 2023 11:42:27 +0200 Subject: [PATCH 2/4] Add verification and installation steps Signed-off-by: Pierangelo Di Pilato --- .../transport-encryption.md | 151 +++++++++++++++++- 1 file changed, 147 insertions(+), 4 deletions(-) diff --git a/docs/eventing/experimental-features/transport-encryption.md b/docs/eventing/experimental-features/transport-encryption.md index 8a76af784d..b6f0d87ef0 100644 --- a/docs/eventing/experimental-features/transport-encryption.md +++ b/docs/eventing/experimental-features/transport-encryption.md @@ -21,9 +21,33 @@ Event producers are be able to connect to HTTPS endpoints with cluster-internal ## 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/). +- 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 @@ -58,5 +82,124 @@ data: ## Verifying that the feature is working -// TODO +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: + # ... +``` From 328ac1b3423245eb31aa9a6e60a1b7019cc6cea5 Mon Sep 17 00:00:00 2001 From: Pierangelo Di Pilato Date: Thu, 3 Aug 2023 12:10:03 +0200 Subject: [PATCH 3/4] Add send event verification steps Signed-off-by: Pierangelo Di Pilato --- .../transport-encryption.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/docs/eventing/experimental-features/transport-encryption.md b/docs/eventing/experimental-features/transport-encryption.md index b6f0d87ef0..fb9d51c5a4 100644 --- a/docs/eventing/experimental-features/transport-encryption.md +++ b/docs/eventing/experimental-features/transport-encryption.md @@ -203,3 +203,94 @@ status: 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 <> /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 +``` \ No newline at end of file From 517b6c208fa0c6bd272bba634e4f15ee1ae9b92e Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Thu, 3 Aug 2023 12:19:44 +0200 Subject: [PATCH 4/4] adding nav bar entry (#3) Signed-off-by: Matthias Wessendorf --- config/nav.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/config/nav.yml b/config/nav.yml index d06c37647d..c63d4981b9 100644 --- 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