knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs for Eventing TLS Beta (#5967) 

* Update docs for Eventing TLS Beta

Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com>

* Reword strict note

Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com>

* Add trust-manager usage note for distributing CA bundles

Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com>

* Add Kafka Broker for KEDA integration

Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com>

* Fix nav

Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com>

* Fix warning formatting

Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com>

---------

Signed-off-by: Pierangelo Di Pilato <pierdipi@redhat.com>
This commit is contained in:
Pierangelo Di Pilato 2024-05-14 18:04:46 +02:00 committed by GitHub
parent 7a7e30c9be
commit 76df699457
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
15 changed files with 231 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
config/nav.yml
View File

@ -277,17 +277,17 @@ nav:
- Configuring logging: eventing/observability/logging/config-logging.md
- Collecting metrics: eventing/observability/metrics/collecting-metrics.md
- Knative Eventing metrics: eventing/observability/metrics/eventing-metrics.md
- Experimental Features:
- About Eventing experimental features: eventing/experimental-features/README.md
- DeliverySpec.Timeout field: eventing/experimental-features/delivery-timeout.md
- DeliverySpec.RetryAfterMax field: eventing/experimental-features/delivery-retryafter.md
- New Trigger Filters: eventing/experimental-features/new-trigger-filters.md
- New APIServerSource Filters: eventing/experimental-features/new-apiserversource-filters.md
- 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
- Sender Identity: eventing/experimental-features/sender-identity.md
- Features:
- About Eventing features: eventing/features/README.md
- DeliverySpec.Timeout field: eventing/features/delivery-timeout.md
- DeliverySpec.RetryAfterMax field: eventing/features/delivery-retryafter.md
- New Trigger Filters: eventing/features/new-trigger-filters.md
- New APIServerSource Filters: eventing/features/new-apiserversource-filters.md
- KReference.Group field: eventing/features/kreference-group.md
- Knative reference mapping: eventing/features/kreference-mapping.md
- EventType auto creation: eventing/features/eventtype-auto-creation.md
- Transport Encryption: eventing/features/transport-encryption.md
- Sender Identity: eventing/features/sender-identity.md
- FAQ: eventing/faq/README.md
# Eventing reference docs
- Reference:

9
config/redirects.yml
View File

@ -2,6 +2,15 @@ plugins:
redirects:
redirect_maps:
contributing/about.md: community/README.md
eventing/experimental-features/README.md: eventing/features/README.md
eventing/experimental-features/delivery-timeout.md: eventing/features/delivery-timeout.md
eventing/experimental-features/delivery-retryafter.md: eventing/features/delivery-retryafter.md
eventing/experimental-features/new-trigger-filters.md: eventing/features/new-trigger-filters.md
eventing/experimental-features/kreference-group.md: eventing/features/kreference-group.md
eventing/experimental-features/kreference-mapping.md: eventing/features/kreference-mapping.md
eventing/experimental-features/eventtype-auto-creation.md: eventing/features/eventtype-auto-creation.md
eventing/experimental-features/transport-encryption.md: eventing/features/transport-encryption.md
eventing/experimental-features/sender-identity.md: eventing/features/sender-identity.md
eventing/broker/kafka-broker/kafka-configmap.md: eventing/configuration/kafka-channel-configuration.md
eventing/broker/create-mtbroker.md: eventing/brokers/create-broker.md
eventing/broker/example-mtbroker.md: eventing/brokers/broker-developer-config-options.md

2
docs/eventing/event-registry.md
View File

@ -152,7 +152,7 @@ two topics.
Using the registry, you can discover the different types of events that [Broker event meshes](../event-mesh) can consume.
!!! note
With the experimental feature for EventType auto creation you can see more event types in the registry. Learn [here](../experimental-features/eventtype-auto-creation) how to enable this feature.
With the feature for EventType auto creation you can see more event types in the registry. Learn [here](../features/eventtype-auto-creation) how to enable this feature.
### View all event types you can subscribe to

31
docs/eventing/experimental-features/README.md → docs/eventing/features/README.md
View File

@ -1,4 +1,4 @@
# Eventing experimental features
# Eventing Features
To keep Knative innovative, the maintainers of this project have developed an
[experimental features process](https://github.com/knative/eventing/blob/main/docs/experimental-features.md)
@ -8,21 +8,22 @@ without affecting the stability of the core project.
<!--TODO: Add note about HOW / where users can provide feedback, otherwise there's not much point mentioning that-->
!!! warning
Experimental features are unstable and may cause issues in your Knative setup or even your cluster setup.
These features should be used with caution, and should never be tested on a production environment. For more
Features are stable and unstable features and may cause issues in your Knative setup or even your cluster
setup.
These features should be used with caution, and should never be tested on a production environment.
For more
information about quality guarantees for features at different stages of
development, see the
[Feature stage definition](https://github.com/knative/eventing/blob/main/docs/experimental-features.md#stage-definition)
documentation.
This document explains how to enable experimental features and which ones are
available today.
This document explains how to enable features and which ones are available today.
## Before you begin
You must have a Knative cluster running with Knative Eventing installed.
## Experimental features configuration
## Features configuration
When you install Knative Eventing, the `config-features` ConfigMap is added to
your cluster in the `knative-eventing` namespace.
@ -40,7 +41,6 @@ metadata:
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
knative.dev/config-propagation: original
knative.dev/config-category: eventing
data:
new-cool-feature: enabled
@ -56,23 +56,22 @@ metadata:
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
knative.dev/config-propagation: original
knative.dev/config-category: eventing
data:
new-cool-feature: disabled
```
## Available experimental features
## Available Features
The following table gives an overview of the available experimental features in
The following table gives an overview of the available features in
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.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. | Beta, enabled 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. | Beta, enabled 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. | Beta, enabled by default |
| [Transport encryption](transport-encryption.md) | `transport-encryption` | Enables components to encrypt traffic using TLS by exposing HTTPS URL. | Alpha, disabled by default |
| [Sender Identity](sender-identity.md) | `authentication-oidc` | Enables Eventing sources to send authenticated requests and addressables to require authenticated requests. | 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. | Beta, enabled by default |
| [Transport encryption](transport-encryption.md) | `transport-encryption` | Enables components to encrypt traffic using TLS by exposing HTTPS URL. | Beta, disabled by default |
| [Sender Identity](sender-identity.md) | `authentication-oidc` | Enables Eventing sources to send authenticated requests and addressables to require authenticated requests. | Alpha, disabled by default |

4
docs/eventing/experimental-features/delivery-retryafter.md → docs/eventing/features/delivery-retryafter.md
View File

@ -25,7 +25,7 @@ of the normal backoff duration and the Retry-After header value will be used for
the subsequent retry attempt. Specifying a "zero" value of `PT0S` effectively
disables **Retry-After** support.
Prior to this experimental feature, Knative Eventing implementations have not
Prior to this feature, Knative Eventing implementations have not
supported **Retry-After** headers, and this is an attempt to provide a path
for standardizing that support. To begin, the feature is **opt-in**, but the
final state will be **opt-out** as follows:
@ -60,7 +60,7 @@ spec:
```
!!! note
While the experimental feature flag enforces all DeliverySpec usage of the
While the feature flag enforces all DeliverySpec usage of the
`retryAfterMax` field through Webhook validation, it does not guarantee all
implementations, such as Channels or Sources, actually implement support
for the field. The shared `HTTPMessageSender.SendWithRetries()` logic has

0
docs/eventing/experimental-features/delivery-timeout.md → docs/eventing/features/delivery-timeout.md
View File

2
docs/eventing/experimental-features/eventtype-auto-creation.md → docs/eventing/features/eventtype-auto-creation.md
View File

@ -26,7 +26,7 @@ data:
...
```
With this experiemental feature enabled, we get `EventType`s on the broker/channel ingress for free, instead of manually creating them as yaml manifests along the application code that talks to the `Broker` or `Channel` API.
With this feature enabled, we get `EventType`s on the broker/channel ingress for free, instead of manually creating them as yaml manifests along the application code that talks to the `Broker` or `Channel` API.
## Example

0
docs/eventing/experimental-features/kreference-group.md → docs/eventing/features/kreference-group.md
View File

2
docs/eventing/experimental-features/kreference-mapping.md → docs/eventing/features/kreference-mapping.md
View File

@ -13,7 +13,7 @@ a [Knative reference](https://github.com/knative/specs/blob/main/specs/eventing/
to a templated URI.
!!! note
Currently only PingSource supports this experimental feature.
Currently only PingSource supports this feature.
For example, you can directly reference non-addressable resources anywhere that
Knative Eventing accepts a reference, such as for a PingSource sink, or a

2
docs/eventing/experimental-features/new-apiserversource-filters.md → docs/eventing/features/new-apiserversource-filters.md
View File

@ -6,7 +6,7 @@
**Tracking issue**: [#7791](https://github.com/knative/eventing/issues/7791)
## Overview
This experimental feature enables a new `filters` field in APIServerSource that conforms to the filters API field defined in the [`CloudEvents Subscriptions API`](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#324-filters). It allows users to specify a set of powerful filter expressions, where each expression evaluates to either true or false for each event.
This feature enables a new `filters` field in APIServerSource that conforms to the filters API field defined in the [`CloudEvents Subscriptions API`](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#324-filters). It allows users to specify a set of powerful filter expressions, where each expression evaluates to either true or false for each event.
The following example shows a APIServerSource using the new `filters` field:

4
docs/eventing/experimental-features/new-trigger-filters.md → docs/eventing/features/new-trigger-filters.md
View File

@ -6,7 +6,7 @@
**Tracking issue**: [#5204](https://github.com/knative/eventing/issues/5204)
## Overview
This experimental feature enables a new `filters` field in Triggers that conforms to the filters API field defined in the [`CloudEvents Subscriptions API`](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#324-filters). It allows users to specify a set of powerful filter expressions, where each expression evaluates to either true or false for each event.
This feature enables a new `filters` field in Triggers that conforms to the filters API field defined in the [`CloudEvents Subscriptions API`](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#324-filters). It allows users to specify a set of powerful filter expressions, where each expression evaluates to either true or false for each event.
The following example shows a Trigger using the new `filters` field:
@ -185,4 +185,4 @@ The reason is twofold. First, at the time of developing `Trigger` APIs, there wa
### Why `filters` and not another name that wouldn't conflict with the `filter` field?
We considered other names, such as `cefilters`, `subscriptionsAPIFilters`, or `enhancedFilters`, but we decided that this would be a step further from aligning with the Subscriptions API. Instead, we decided it is a good opportunity to conform with the Subscriptions API, at least at the field name level, and to leverage the safety of this being an experimental feature.
We considered other names, such as `cefilters`, `subscriptionsAPIFilters`, or `enhancedFilters`, but we decided that this would be a step further from aligning with the Subscriptions API. Instead, we decided it is a good opportunity to conform with the Subscriptions API, at least at the field name level, and to leverage the safety of this being a feature.

0
docs/eventing/experimental-features/sender-identity.md → docs/eventing/features/sender-identity.md
View File

195
docs/eventing/experimental-features/transport-encryption.md → docs/eventing/features/transport-encryption.md
View File

@ -2,7 +2,7 @@
**Flag name**: `transport-encryption`
**Stage**: Alpha, disabled by default
**Stage**: Beta, disabled by default
**Tracking issue**: [#5957](https://github.com/knative/eventing/issues/5957)
@ -28,15 +28,103 @@ Event producers are be able to connect to HTTPS endpoints with cluster-internal
## Installation
### Setup `SelfSigned` `ClusterIssuer`
!!! note
ClusterIssuers, are Kubernetes resources that represent certificate authorities (CAs) that are able
to generate signed certificates by honoring certificate signing requests. All cert-manager
certificates require a referenced issuer that is in a ready condition to attempt to honor the
request.
Reference: cert-manager.io/docs/concepts/issuer/
!!! important
For the simplicity of this guide, we will use a `SelfSigned` issuer as root certificate, however, be
aware of the implications and limitations as documented at
cert-manager.io/docs/configuration/selfsigned/ of this method.
If you’re running your company specific Private Key Infrastructure (PKI), we recommend the CA
issuer. Refer to the cert-manager documentation for more details:
cert-manager.io/docs/configuration/ca/, however, you can use any other issuer that is usable for
cluster-local services.
1. Create a `SelfSigned` `ClusterIssuer`:
```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: knative-eventing-selfsigned-issuer
spec:
selfSigned: {}
```
2. Apply the `ClusterIssuer` resource:
```shell
$ kubectl apply -f <filename>
```
3. Create a root certificate using the previously created `SelfSigned` `ClusterIssuer`:
```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: knative-eventing-selfsigned-ca
namespace: cert-manager # the cert-manager operator namespace
spec:
# Secret name later used for the ClusterIssuer for Eventing
secretName: knative-eventing-ca
isCA: true
commonName: selfsigned-ca
privateKey:
algorithm: ECDSA
size: 256
issuerRef:
name: knative-eventing-selfsigned-issuer
kind: ClusterIssuer
group: cert-manager.io
```
4. Apply the `Certificate` resource:
```yaml
$ kubectl apply -f <filename>
```
### Setup `ClusterIssuer` for Eventing
1. Create the `knative-eventing-ca-issuer` `ClusterIssuer` for Eventing:
```yaml
# This is the issuer that every Eventing component use to issue their server's certs.
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: knative-eventing-ca-issuer
spec:
ca:
# Secret name in the Cert-Manager Operator namespace (cert-manager by default) containing
# the certificate that can then be used by Knative Eventing components for new certificates.
secretName: knative-eventing-ca
```
!!! important
The name of the `ClusterIssuer` must be `knative-eventing-ca-issuer`.
2. Apply the `ClusterIssuer` resource:
```yaml
$ kubectl apply -f <filename>
```
### Install the certificates for Eventing components
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
the release assets, we release the certificates for Eventing servers that can be customized as
necessary.
1. Install issuers and certificates, run the following command:
1. Install certificates, run the following command:
```shell
kubectl apply -f {{ artifact(repo="eventing",file="eventing-tls-networking.yaml")}}
```
2. Verify issuers and certificates are ready
2. [Optional] If you're using Eventing Kafka components, install certificates for Kafka components
by running the following command:
```shell
kubectl apply -f {{ artifact(repo="eventing-kafka-broker",file="eventing-kafka-tls-networking.yaml")}}
```
3. Verify issuers and certificates are ready
```shell
kubectl get certificates.cert-manager.io -n knative-eventing
```
@ -47,6 +135,7 @@ necessary.
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
@ -67,6 +156,11 @@ The possible values for `transport-encryption` are:
- Addressables must not accept events to non-HTTPS endpoints
- Addressables must only advertise HTTPS endpoints
!!! important
The `strict` is only enforced on the Broker and Channel receiver/ingress.
When a broker or channel sends events to a subscriber, if that subscriber only has an HTTP
address, the broker or channel can still send events over HTTP instead of HTTPS
For example, to enable `strict` transport encryption, the `config-features` ConfigMap will look like
the following:
@ -80,21 +174,53 @@ data:
transport-encryption: "strict"
```
## Trusting CA for a specific event sender
## Configure additional CA trust bundles
Event sources, triggers or subscriptions are considered event senders and they can be configured to
By default, Eventing clients trusts the system root CA (public CA).
If you need to add additional CA bundles for Eventing, you can do so by creating ConfigMaps in the
`knative-eventing` namespace with label `networking.knative.dev/trust-bundle: true`:
!!! important
Whenever CA bundles `ConfigMaps` are updated, the Eventing clients will automatically add them to
their trusted CA bundles when a new connection is established.
1. Create a CA bundle for Eventing:
```yaml
kind: ConfigMap
metadata:
name: my-org-eventing-bundle
namespace: knative-eventing
labels:
networking.knative.dev/trust-bundle: "true"
# All data keys containing valid PEM-encoded CA bundles will be trusted by Eventing clients.
data:
ca.crt: ...
ca1.crt: ...
tls.crt: ...
```
!!! important
Use a name that is unlikely to conflict with existing or future Eventing-provided `ConfigMap` name.
For distributing CA trust bundles, you can leverage [trust-manager](https://cert-manager.io/docs/trust/trust-manager/),
however, it is not required.
### Trusting CA for a specific event sender
Event sources, triggers or subscriptions are considered event senders, and they can be configured to
trust specific CA certificates.
!!! important
The CA certs must be PEM formatted certificates. Since it's a multi-line YAML string make sure that
the `CACerts` value is indented correctly, otherwise when creating the resource it will be rejected.
Triggers and subscriptions can be configured as follow:
Triggers and subscriptions can be configured as follows:
```yaml
spec:
# ...
subscriber:
uri: https://mycorp-internal-example.com/v1/api
CACerts: |-
@ -131,12 +257,12 @@ spec:
-----END CERTIFICATE-----
```
Similarly, sources can be configured as follow:
Similarly, sources can be configured as follows:
```yaml
spec:
# ...
sink:
uri: https://mycorp-internal-example.com/v1/api
CACerts: |-
@ -173,6 +299,54 @@ spec:
-----END CERTIFICATE-----
```
### Configure custom event sources to trust the Eventing CA
The recommended way of creating custom event sources is using a SinkBinding, SinkBinding will inject
the configured CA trust bundles as projected volume into each container using the directory
`/knative-custom-certs`.
!!! note
Some organizations might inject company specific CA trust bundles into base container images and
automatically configure runtimes (openjdk, node, etc) to trust that CA bundle.
In that case, you might not need to configure your clients.
Using the previous example of the my-org-eventing-bundle ConfigMap with data keys being ca.crt,
ca1.crt and tls.crt, you will have a `/knative-custom-certs` directory that will have the following
layout:
```bash
/knative-custom-certs/ca.crt
/knative-custom-certs/ca1.crt
/knative-custom-certs/tls.crt
```
Those files can then be used to add CA trust bundles to HTTP clients sending events to Eventing.
!!!note
Depending on the runtime, programming language or library that you’re using, there are different
ways of configuring custom CA certs files using command line flags, environment variables, or by
reading the content of those files.
Refer to their documentation for more details.
### Adding `SelfSigned` `ClusterIssuer` to CA trust bundles
In case you are using a SelfSigned ClusterIssuer as described in the [Setup SelfSigned
ClusterIssuer section](#setup-selfsigned-clusterissuer), you can add the CA to the Eventing CA trust
bundles by running the following commands:
1. Export the CA from the knative-eventing-ca secret in the OpenShift Cert-Manager Operator namespace, cert-manager by default:
```shell
$ kubectl get secret -n cert-manager knative-eventing-ca -o=jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
```
2. Create a CA trust bundle in the `knative-eventing` namespace:
```shell
$ kubectl create configmap -n knative-eventing my-org-selfsigned-ca-bundle --from-file=ca.crt
```
3. Label the ConfigMap with networking.knative.dev/trust-bundle: "true" label:
```shell
$ kubectl label configmap -n knative-eventing my-org-selfsigned-ca-bundle networking.knative.dev/trust-bundle=true
```
## Verifying that the feature is working
Save the following YAML into a file called `default-broker-example.yaml`
@ -234,6 +408,7 @@ 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
```

4
docs/eventing/sources/kafka-source/README.md
View File

@ -208,7 +208,7 @@ Alternatively, if you are using a GitOps approach, you can add the `consumers` k
### Automatic Scaling with KEDA
Kafka Sources have experimental (Alpha) support for serverless scaling with KEDA, including scale to zero. If you want Knative and KEDA to scale your Kafka source for you,
Kafka Sources and Brokers for Apache Kafka have (Alpha) support for serverless scaling with KEDA, including scale to zero. If you want Knative and KEDA to scale your Kafka source for you,
you must [install KEDA](https://keda.sh/docs/2.13/deploy/), and then enable the feature flag.
To enable the feature flag, you need to create or modify the `config-kafka-features` configmap in the `knative-eventing` namespace. You can create the file as below:
@ -226,7 +226,7 @@ To enable the feature flag, you need to create or modify the `config-kafka-featu
```
From there, apply the configmap into your cluster and assuming that KEDA is also installed your Kafka Sources will scale for you! For more information on other values you
can add to the `config-kafka-features` configmap, [read about the experimental Kafka Broker features](../../brokers/broker-types/kafka-broker/configuring-kafka-features).
can add to the `config-kafka-features` configmap, [read about the Kafka Broker features](../../brokers/broker-types/kafka-broker/configuring-kafka-features).
### Verify

2
docs/eventing/triggers/README.md
View File

@ -102,7 +102,7 @@ This example filters events from the `default` broker that are of type
### New trigger filters
If you need more powerful filtering options, you can use the [new trigger filters](../experimental-features/new-trigger-filters.md).
If you need more powerful filtering options, you can use the [new trigger filters](../features/new-trigger-filters.md).
## Trigger annotations
You can modify a Trigger's behavior by setting the following two annotations: