diff --git a/docs/interceptors.md b/docs/interceptors.md index 8c4707c77..eec5ae6e7 100644 --- a/docs/interceptors.md +++ b/docs/interceptors.md @@ -24,7 +24,7 @@ transformation, define and test trigger conditions, and implement other useful p the payload data to the `TriggerBinding`. You can also use an `Interceptor` to modify the behavior of the associated `Trigger`. Tekton Triggers currently supports two distinct `Interceptor` implementations: -- Standalone `Interceptors`, which are instances of the [`ClusterInterceptor`](./clusterinterceptors.md) Custom Resource Definition (CRD). You specify these `Interceptors` by referencing them, +- Standalone `Interceptors`, which are instances of the [`Interceptor`](./namespacedinterceptor) or the [`ClusterInterceptor`](./clusterinterceptors.md) Custom Resource Definition (CRD). You specify these `Interceptors` by referencing them, along with the desired parameters, within your `EventListener`. You can use the `ClusterInterceptor` CRD to implement your own custom `Interceptors`. - Legacy `Interceptors`, which you define entirely as part of the `EventListener` definition. This implementation will eventually be deprecated, so please consider transitioning to standalone `Interceptors` as soon as possible. See [TEP-0026](https://github.com/tektoncd/community/blob/main/teps/0026-interceptor-plugins.md) for more context on this change. @@ -42,9 +42,9 @@ Tekton Triggers ships with the following `Interceptors` to help you get started: To specify an `Interceptor` within your `EventListener`, create an `interceptors:` field with the following sub-fields: - `name` - (optional) a name that uniquely identifies this `Interceptor` definition -- `ref` - a reference to a [`ClusterInterceptor`](./clusterinterceptors.md) object with the following fields: +- `ref` - a reference to a [`ClusterInterceptor`](./clusterinterceptors.md) or [`Interceptor`](./namespacedinterceptors.md) object with the following fields: - `name` - the name of the referenced `ClusterInterceptor` - - `kind` - (optional) specifies that the referenced Kubernetes object is a `ClusterInterceptor` object + - `kind` - (optional) specifies that whether the referenced Kubernetes object is a `ClusterInterceptor` object or `NamespacedInterceptor`. Default value is `ClusterInterceptor` - `apiVersion` - (optional) specifies the target API version, for example `triggers.tekton.dev/v1alpha1` - `params` - `name`/`value` pairs that specify the parameters you want to pass to the `ClusterInterceptor` - `params` - (optional) `name`/`value` pairs that specify the desired parameters for the `Interceptor`; @@ -565,4 +565,4 @@ field both in the body of the payload as well as via the extra fields added to t ## Implementing custom `Interceptors` -Tekton Triggers ships with the `ClusterInterceptor` Custom Resource Definition (CRD), which you can use to implement custom `Interceptors`. See [`ClusterInterceptors`](./clusterinterceptors.md) for more information. +Tekton Triggers ships with the `ClusterInterceptor`and `Interceptor` Custom Resource Definition (CRD), which you can use to implement custom `Interceptors`. See [`ClusterInterceptors`](./clusterinterceptors.md) and [`NamespacedInterceptors`](./namespacedinterceptors.md) for more information. diff --git a/docs/namespacedinterceptors.md b/docs/namespacedinterceptors.md new file mode 100644 index 000000000..2edbbbc07 --- /dev/null +++ b/docs/namespacedinterceptors.md @@ -0,0 +1,76 @@ + +# `Interceptors` + +Tekton Triggers ships with the `Interceptor` Custom Resource Definition (CRD), which allows you to implement a custom namespaced-scoped Webhook-style `Interceptor`. + +A `Interceptor` specifies an external Kubernetes v1 Service running custom business logic that receives the event payload from the +`EventListener` via an HTTP request and returns a processed version of the payload along with an HTTP 200 response. The `Interceptor` can also +halt processing if the event payload does not meet criteria you have configured as well as add extra fields that are accessible in the `EventListener's` +top-level `extensions` field to other [`Interceptors`](interceptors.md) and `Interceptors` chained with it and the associated `TriggerBinding`. + +## Structure of a `Interceptor` + +A `Interceptor` definition consists of the following fields: + +- Required: + - [`apiVersion`][kubernetes-overview] - specifies the target API version, for example `triggers.tekton.dev/v1alpha1` + - [`kind`][kubernetes-overview] - specifies that this Kubernetes resource is a `Interceptor` object + - [`metadata`][kubernetes-overview] - specifies data that uniquely identifies this `Interceptor` object, for example a `name` + - [`spec`][kubernetes-overview] - specifies the configuration information for this `Interceptor` object, including: + - [`clientConfig`] - specifies how a client, such as an `EventListener` communicates with this `Interceptor` object + +[kubernetes-overview]: + https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + +## Configuring the client of the `Interceptor` + +The `clientConfig` field specifies the client, such as an `EventListener` and how it communicates with the `Interceptor` to exchange +event payload and other data. You can configure this field in one of the following ways: + +- Specify the `url` field and as its value a URL at which the corresponding Kubernetes service listens for incoming requests from this `Interceptor` +- Specify the `service` field and within it reference the corresponding Kubernetes service that's listening for incoming requests from this `Interceptor` + +For example: + +```yaml +spec: + clientConfig: + url: "http://interceptor-svc.default.svc/" +--- +spec: + clientConfig: + service: + name: "my-interceptor-svc" + namespace: "default" + path: "/optional-path" # optional + port: 8081 # defaults to 80 +``` + +## Configuring a Kubernetes Service for the `Interceptor` + +The Kubernetes object running the custom business logic for your `Interceptor` must meet the following criteria: + +- Fronted by a regular Kubernetes v1 Service listening on an HTTP port (default port is 80) +- Accepts an HTTP `POST` request that contains an [`InterceptorRequest`](https://pkg.go.dev/github.com/tektoncd/triggers/pkg/apis/triggers/v1alpha1#InterceptorRequest) + as a JSON body +- Returns an HTTP 200 OK response that contains an [`InterceptorResponse`](https://pkg.go.dev/github.com/tektoncd/triggers/pkg/apis/triggers/v1alpha1#InterceptorResponse) + as a JSON body. If the trigger processing should continue, the interceptor should set the `continue` field in the response to `true`. If the processing should be stopped, the interceptor should set the `continue` field to `false` and also provide additional information detailing the error in the `status` field. +- Returns a response other than HTTP 200 OK only if payload processing halts due to a catastrophic failure. + +### Running Interceptor as HTTPS + +Triggers support writing custom interceptor for both `http` and `https`. Support of `http` for custom interceptor will be removed in future and only `https` will be supported. + +End user who write `https` custom interceptor need to pass `caBundle` as well as label +```yaml + labels: + server/type: https +``` +to `Interceptor` in order to make secure connection with eventlistener. + +Here is the reference for writing [https server for custom interceptor](https://github.com/tektoncd/triggers/blob/main/cmd/interceptors/main.go). diff --git a/docs/triggers.md b/docs/triggers.md index 820d2b586..1d5353e64 100644 --- a/docs/triggers.md +++ b/docs/triggers.md @@ -22,6 +22,9 @@ When creating a `Trigger` definition you must specify the required fields and ca definition using a `name`/`value` pair. - [`template`] - Specifies the corresponding `TriggerTemplate` either as a reference as an embedded `TriggerTemplate` definition. - [`interceptors`] - (Optional) specifies one or more `Interceptors` that will process the payload data before passing it to the `TriggerTemplate`. + - `ref` - a reference to a [`ClusterInterceptor`](./clusterinterceptors.md) or [`Interceptor`](./namespacedinterceptors.md) object with the following fields: + - `name` - the name of the referenced `ClusterInterceptor` + - `kind` - (Optional) specifies that whether the referenced Kubernetes object is a `ClusterInterceptor` object or `NamespacedInterceptor`. Default value is `ClusterInterceptor` - [`serviceAccountName`] - (Optional) Specifies the `ServiceAccount` to supply to the `EventListener` to instantiate/execute the target resources. Below is an example `Trigger` definition: