mirror of https://github.com/knative/docs.git
Document transport-encryption Eventing feature (#5642)
* Document transport-encryption feature Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com> * Add verification and installation steps Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com> * Add send event verification steps Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com> * adding nav bar entry (#3) Signed-off-by: Matthias Wessendorf <mwessend@redhat.com> --------- Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com> Signed-off-by: Matthias Wessendorf <mwessend@redhat.com> Co-authored-by: Matthias Wessendorf <mwessend@redhat.com>
This commit is contained in:
Pierangelo Di Pilato
GitHub
parent
4691b86f62
commit
c9f29b93e9
|
|
@ -280,6 +280,7 @@ nav:
|
||||||
- KReference.Group field: eventing/experimental-features/kreference-group.md
|
- KReference.Group field: eventing/experimental-features/kreference-group.md
|
||||||
- Knative reference mapping: eventing/experimental-features/kreference-mapping.md
|
- Knative reference mapping: eventing/experimental-features/kreference-mapping.md
|
||||||
- EventType auto creation: eventing/experimental-features/eventtype-auto-creation.md
|
- EventType auto creation: eventing/experimental-features/eventtype-auto-creation.md
|
||||||
|
- Transport Encryption: eventing/experimental-features/transport-encryption.md
|
||||||
# Eventing reference docs
|
# Eventing reference docs
|
||||||
- Reference:
|
- Reference:
|
||||||
- Eventing API: eventing/reference/eventing-api.md
|
- Eventing API: eventing/reference/eventing-api.md
|
||||||
|
|
|
||||||
|
|
@ -67,10 +67,11 @@ data:
|
||||||
The following table gives an overview of the available experimental features in
|
The following table gives an overview of the available experimental features in
|
||||||
Knative Eventing:
|
Knative Eventing:
|
||||||
|
|
||||||
| Feature | Flag | Description | Maturity |
|
| 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.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 |
|
| [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 |
|
| [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 |
|
| [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 |
|
| [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 |
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue