You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The [Watcher CR](https://github.com/kyma-project/lifecycle-manager/blob/main/api/v1beta2/watcher_types.go#L121) configures the Kyma Control Plane (KCP) setup and Runtime Watcher on Kyma runtimes. Read the following document to see the the parameters the CR consists of.
4
-
5
-
## Runtime-Watcher configuration
6
-
7
-
### **spec.resourceToWatch**
8
-
9
-
Defines which resources the Runtime Watcher watches. By default, the **version** value is a wildcard (`*`), so an update is not required after the API version changes.
3
+
The [Watcher CR](https://github.com/kyma-project/lifecycle-manager/blob/main/api/v1beta2/watcher_types.go) configures the Kyma Control Plane (KCP) setup and Runtime Watcher on Kyma runtimes. Read the following document to see the parameters that the CR consists of.
10
4
11
5
```yaml
6
+
apiVersion: operator.kyma-project.io/v1beta2
7
+
kind: Watcher
8
+
metadata:
9
+
name: <name>
10
+
namespace: kcp-system
12
11
spec:
13
12
resourceToWatch:
14
-
group: operator.kyma-project.io
15
-
version: "*"
16
-
resource: kymas
17
-
```
18
-
19
-
### **spec.labelsToWatch**
20
-
21
-
> **NOTE:** The resources you're watching must have the `operator.kyma-project.io/watched-by` label.
22
-
23
-
With the **spec.labelsToWatch** attribute, you can filter the specified Group/Version/Kind (GVK) in **spec.resourceToWatch**. For example, if the specified GVK is `secrets`, then it is useful to filter them by a specific label, otherwise, the Runtime Watcher would send an event to the KCP for every Create/Read/Update/Delete (CRUD) event of any Secret in the Kyma cluster.
The **spec.resourceToWatch** field specifies the GVK of the resources Runtime Watcher watches. Note that **spec.resourceToWatch.resource** must be the API resource name, not the kind of the resource. For example, it must be "configmaps" instead of "ConfigMap". It is possible to specify the wildcard `*` for **spec.resourceToWatch.version**.
38
33
39
-
It uses either the `spec` or `status` value to define if Runtime Watcher sends an event to KCP if the spec of the specified GVK or the status changes.
34
+
### Labels to Watch
40
35
41
-
### **spec.manager**
36
+
Optionally, the **spec.labelsToWatch** field allows to filter the resources by a specific label value.
42
37
43
-
Specifies the component responsible for handling webhook requests from Runtime Watcher. This field determines the routing path for webhook validation requests to KCP (`/validate/<manager-value>`).
38
+
> [!NOTE]
39
+
> Runtime Watcher does not provide a mechanism to add this label to the resources. You must ensure that the resources you want to watch have this label.
44
40
45
-
```yaml
46
-
spec:
47
-
manager: "lifecycle-manager"
48
-
```
41
+
### Field
49
42
50
-
> ### Note:
51
-
> **Backward Compatibility:** If you don't set **spec.manager**, the system falls back to the `operator.kyma-project.io/managed-by` label for backward compatibility. However, this label-based approach is deprecated and will be removed in a future version. It is recommended to migrate to using the **spec.manager** field.
43
+
The **spec.field** field specifies what parts of the watched object trigger events. Allowed values are `spec` and `status`.
52
44
53
-
## KCP configuration
45
+
If `status` is specified, watch events are only emitted if the `.status` subresource of the watched object changes. The ValidatingWebhookConfiguration is configured to watch only the status subresource. For example, "pods/status" instead of "pods".
54
46
55
-
### **spec.serviceInfo**
47
+
If `spec` is specified, watch events are only emitted if the `.spec` field of the watched object changes. If the object doesn't contain a `.spec` field, it falls back to emit a watch event on **any** change to the object, including changes to metadata or status.
56
48
57
-
Specifies to which name, Namespace, and port the incoming events are routed.
49
+
### Manager
58
50
59
-
```yaml
60
-
spec:
61
-
name: klm-event-service
62
-
namespace: kcp-system
63
-
port: 8082
64
-
```
51
+
The **spec.manager** field defines the URL path to which the Runtime Watcher sends events. The entire path follows the format `/v2/<spec.manager>/event`. Accordingly, a VirtualService is created that matches the prefix `/v2/<spec.manager>/event` and routes received requests to the Service defined in **spec.serviceInfo**.
65
52
66
-
### **spec.gateway**
53
+
> [!NOTE]
54
+
> In Kyma runtime, this setting configures the ValidatingWebhookConfiguration to call `/validate/<spec.manager>` of the Runtime Watcher deployment.
67
55
68
-
Defines to which label selector of a Gateway the VirtualService binds.
The **spec.serviceInfo** specifies the name, namespace, and port to which events received from the Runtime Watcher are routed.
77
59
78
-
## Labels
60
+
### Gateway
79
61
80
-
- **`operator.kyma-project.io/managed-by`:** **[DEPRECATED]** This label previously specified the module that manages and listens to the Watcher CR's corresponding webhook. The value was used to generate the path in KCP for webhook requests (`/validate/<label-value>`).
81
-
82
-
> ### Caution
83
-
> The `operator.kyma-project.io/managed-by` label is deprecated. Use the **spec.manager** field instead. The label-based fallback will be removed in a future API version. For more information, see the [**spec.manager**](#specmanager) section.
62
+
The **spec.gateway** field defines the label selector of the Istio Gateway in KCP. Don't change the default value.
@@ -8,196 +8,68 @@ The Watcher mechanism is deployed to the SKR as `ValidatingWebhookConfiguration`
8
8
9
9
To set up a watch on a resource, you must define and apply a Watcher CR for it. The Watcher CR defines which resources Runtime Watcher notifies changes for and where to forward the events in KCP.
10
10
11
-
Here is the definition of the Watcher CR. The detailed filed descriptions are provided below in the [Resources to Watch](#resources-to-watch) and [Events to Consume](#events-to-consume) sections.
11
+
Here is an example of the Watcher CR. The detailed field descriptions are provided in the [Watcher API definition](./api.md).
For more information, see the [Watcher API definition](./api.md).
38
+
## Consuming Events
40
39
41
-
### Resources to Watch
42
-
43
-
The **spec.resourceToWatch** field specifies the GVK of the resources Runtime Watcher watches.
44
-
45
-
These resources must have the `operator.kyma-project.io/watched-by` label. The **spec.labelsToWatch** field allows you to filter the resources by a specific label value.
46
-
47
-
> [!NOTE]
48
-
> Runtime Watcher does not provide a mechanism to add this label to the resources. You must ensure that the resources you want to watch have this label.
49
-
50
-
Using the **spec.field** field, you can choose between values `spec` or `status`, to set either the `status` subresource as a notification trigger or the `spec` field.
51
-
52
-
See an example of a Watcher CR that watches changes on Secrets' spec:
The **spec.serviceInfo** field specifies the name, namespace, and port to which the events are routed.
68
-
69
-
The **spec.gateway** field defines the label selector of the Istio Gateway in KCP. Don't change the default value.
70
-
71
-
See an example of a Watcher CR that forwards events to the `my-operator-service` service in the `my-system` namespace on port `8080`:
72
-
73
-
```yaml
74
-
spec:
75
-
serviceInfo:
76
-
name: my-operator-service
77
-
namespace: my-system
78
-
port: 8080
79
-
```
80
-
81
-
The service receiving the events can be any arbitrary service that is listening on the specified port, or it can be a k8s controller using the [Listener package](./listener.md).
82
-
83
-
This is the request body of the event that is sent to the service:
40
+
The service receiving the events can be any arbitrary service that is listening on the specified port. Behind the service, there must be a consumer expecting POST requests on `/v2/<spec.manager>/event` with the following content:
The **owner** field contains the namespaced name of the resource that owns the watched resource. It is the reference to the resource in KCP that should be reconciled when the event is received. It is parsed from the `operator.kyma-project.io/owned-by` label on the watched resource in the `<namespace>/<name>` format.
104
-
105
-
## Examples
106
-
107
-
### Arbitrary Service
108
-
109
-
It is possible to consume events in any arbitrary service that listens on the specified port. It receives the Events as POST requests on the route `/v1/<operator-name>/event`. This <operator-name> is the value of the `operator.kyma-project.io/managed-by` label in the Watcher CR.
110
-
111
-
See a Golang example of a server that listens on port `8080` and prints the received events:
112
-
113
-
```go
114
-
package main
115
-
import (
116
-
"fmt"
117
-
"io"
118
-
"log"
119
-
"net/http"
120
-
)
121
-
func main() {
122
-
http.HandleFunc("/v1/my-operator/event", func(w http.ResponseWriter, r *http.Request) {
To identify the Kyma runtime from which the received event originates, the Runtime Id can be extracted from the Common Name of the certificate attached to the request. The certificate attached to the request is available as an HTTP header, and the `listener` package provides the [`GetCertificateFromHeader()`](https://github.com/kyma-project/runtime-watcher/blob/de2f534ce7c0c73da817505c9aad0db12f966b27/listener/pkg/v2/certificate/parse_certificate.go#L26-L65) helper function to extract it. It can be used as follows:
fmt.Sprintf("could not get client certificate from request: %v", err),
57
+
http.StatusUnauthorized,
58
+
}
59
+
}
60
+
61
+
if clientCertificate.Subject.CommonName == "" {
62
+
return "", &UnmarshalError{
63
+
"client certificate common name is empty",
64
+
http.StatusBadRequest,
65
+
}
66
+
}
67
+
68
+
return clientCertificate.Subject.CommonName, nil
131
69
}
132
70
```
133
71
134
-
### Listener Package
135
-
136
-
The listener package simplifies setting up an endpoint for an operator residing in KCP, which receives events sent by the Watcher to KCP. It provides a simple API to register a handler for the event type and start the server in a controller.
137
-
138
-
See an example of setting up a listener in a controller and reconciling the owner resource:
For further convenience, the `listener` package also provides a [`SKREventListener`](../listener/pkg/v2/event/skr_events_listener.go#L32-L43) that handles the requests and exposes a channel via [`ReceivedEvents()`](../listener/pkg/v2/event/skr_events_listener.go#L46-L54) providing an unstructured object for every received event. For an example in Lifecycle Manager, see:
202
73
203
-
The package provides a `SKREventListener` struct that implements the `Runnable` interface. The `SKREventListener` struct listens on the specified port and verifies the incoming events. The `ReceivedEvents` channel is used to receive the events. The `SKREventListener` struct is added to the manager, and the controller watches the `ReceivedEvents` channel to reconcile the owner resource through WatcherRawSource.
0 commit comments