mirror of https://github.com/knative/docs.git
245 lines
9.7 KiB
Markdown
245 lines
9.7 KiB
Markdown
# ApiServerSource reference
|
|
|
|
|
|
|
|
This topic provides reference information about the configurable fields for the
|
|
ApiServerSource object.
|
|
|
|
|
|
## ApiServerSource
|
|
|
|
An ApiServerSource definition supports the following fields:
|
|
|
|
| Field | Description | Required or optional |
|
|
|-------|-------------|----------------------|
|
|
| [`apiVersion`][kubernetes-overview] | Specifies the API version, for example `sources.knative.dev/v1`. | Required |
|
|
| [`kind`][kubernetes-overview] | Identifies this resource object as an ApiServerSource object. | Required |
|
|
| [`metadata`][kubernetes-overview] | Specifies metadata that uniquely identifies the ApiServerSource object. For example, a `name`. | Required |
|
|
| [`spec`][kubernetes-overview] | Specifies the configuration information for this ApiServerSource object. | Required |
|
|
| `spec.mode` | EventMode controls the format of the event. Set to `Reference` to send a `dataref` event type for the resource being watched. Only a reference to the resource is included in the event payload. Set to `Resource` to have the full resource lifecycle event in the payload. Defaults to `Reference`. | Optional |
|
|
| [`spec.owner`](#owner-parameter) | ResourceOwner is an additional filter to only track resources that are owned by a specific resource type. If ResourceOwner matches Resources[n] then Resources[n] is allowed to pass the ResourceOwner filter. | Optional |
|
|
| [`spec.resources`](#resources-parameter) | The resources that the source tracks so it can send related lifecycle events from the Kubernetes ApiServer. Includes an optional label selector to help filter. | Required |
|
|
| `spec.serviceAccountName` | The name of the ServiceAccount to use to run this source. Defaults to `default` if not set. | Optional |
|
|
| [`spec.sink`](#sink-parameter) | A reference to an object that resolves to a URI to use as the sink. | Required |
|
|
| [`spec.ceOverrides`](#cloudevent-overrides) | Defines overrides to control the output format and modifications to the event sent to the sink. | Optional |
|
|
|
|
|
|
### Owner parameter
|
|
|
|
ResourceOwner is an additional filter to only track resources that are owned by
|
|
a specific resource type. If ResourceOwner matches Resources[n] then Resources[n]
|
|
is allowed to pass the ResourceOwner filter.
|
|
|
|
An `owner` definition supports the following fields:
|
|
|
|
| Field | Description | Required or optional |
|
|
|-------|-------------|----------------------|
|
|
| `apiVersion` | API version of the resource to watch. | Required |
|
|
| [`kind`][kubernetes-kinds] | Kind of the resource to watch. | Required |
|
|
|
|
#### Example: Owner parameter
|
|
|
|
```yaml
|
|
apiVersion: sources.knative.dev/v1
|
|
kind: ApiServerSource
|
|
metadata:
|
|
name: <apiserversource>
|
|
namespace: <namespace>
|
|
spec:
|
|
...
|
|
owner:
|
|
apiVersion: apps/v1
|
|
kind: Deployment
|
|
...
|
|
```
|
|
|
|
|
|
### Resources parameter
|
|
|
|
The `resources` parameter specifies the resources that the source tracks so that
|
|
it can send related lifecycle events from the Kubernetes ApiServer.
|
|
The parameter includes an optional label selector to help filter.
|
|
|
|
A `resources` definition supports the following fields:
|
|
|
|
| Field | Description | Required or optional |
|
|
|-------|-------------|----------------------|
|
|
| `apiVersion` | API version of the resource to watch. | Required |
|
|
| [`kind`][kubernetes-kinds] | Kind of the resource to watch. | Required |
|
|
| [`selector`][label-selectors] | LabelSelector filters this source to objects to those resources pass the label selector. <!-- unsure what this means --> | Optional |
|
|
| `selector.matchExpressions` | A list of label selector requirements. The requirements are ANDed. | Use one of `matchExpressions` or `matchLabels` |
|
|
| `selector.matchExpressions.key` | The label key that the selector applies to. | Required if using `matchExpressions` |
|
|
| `selector.matchExpressions.operator` | Represents a key's relationship to a set of values. Valid operators are `In`, `NotIn`, `Exists` and `DoesNotExist`. | Required if using `matchExpressions` |
|
|
| `selector.matchExpressions.values` | An array of string values. If `operator` is `In` or `NotIn`, the values array must be non-empty. If `operator` is `Exists` or `DoesNotExist`, the values array must be empty. This array is replaced during a strategic merge patch. | Required if using `matchExpressions` |
|
|
| `selector.matchLabels` | A map of key-value pairs. Each key-value pair in the `matchLabels` map is equivalent to an element of `matchExpressions`, where the key field is `matchLabels.<key>`, the `operator` is `In`, and the `values` array contains only "matchLabels.<value>". The requirements are ANDed. | Use one of `matchExpressions` or `matchLabels` |
|
|
|
|
#### Example: Resources parameter
|
|
|
|
Given the following YAML, the ApiServerSource object receives events for all Pods
|
|
and Deployments in the namespace: <!-- is this correct? -->
|
|
|
|
```yaml
|
|
apiVersion: sources.knative.dev/v1
|
|
kind: ApiServerSource
|
|
metadata:
|
|
name: <apiserversource>
|
|
namespace: <namespace>
|
|
spec:
|
|
# ...
|
|
resources:
|
|
- apiVersion: v1
|
|
kind: Pod
|
|
- apiVersion: apps/v1
|
|
kind: Deployment
|
|
```
|
|
|
|
#### Example: Resources parameter using matchExpressions
|
|
|
|
Given the following YAML, ApiServerSource object receives events for all Pods in
|
|
the namespace that have a label `app=myapp` or `app=yourapp`: <!-- is this correct? -->
|
|
|
|
```yaml
|
|
apiVersion: sources.knative.dev/v1
|
|
kind: ApiServerSource
|
|
metadata:
|
|
name: <apiserversource>
|
|
namespace: <namespace>
|
|
spec:
|
|
# ...
|
|
resources:
|
|
- apiVersion: v1
|
|
kind: Pod
|
|
selector:
|
|
matchExpressions:
|
|
- key: app
|
|
operator: In
|
|
values:
|
|
- myapp
|
|
- yourapp
|
|
```
|
|
|
|
#### Example: Resources parameter using matchLabels
|
|
|
|
Given the following YAML, the ApiServerSource object receives events for all Pods
|
|
in the namespace that have a label `app=myapp`: <!-- is this correct? -->
|
|
|
|
```yaml
|
|
apiVersion: sources.knative.dev/v1
|
|
kind: ApiServerSource
|
|
metadata:
|
|
name: <apiserversource>
|
|
namespace: <namespace>
|
|
spec:
|
|
# ...
|
|
resources:
|
|
- apiVersion: v1
|
|
kind: Pod
|
|
selector:
|
|
matchLabels:
|
|
app: myapp
|
|
```
|
|
|
|
|
|
### Sink parameter
|
|
|
|
Sink is a reference to an object that resolves to a URI to use as the sink.
|
|
|
|
A `sink` definition supports the following fields:
|
|
|
|
| Field | Description | Required or optional |
|
|
|-------|-------------|----------------------|
|
|
| `ref` | This points to an Addressable. | Required if _not_ using `uri` |
|
|
| `ref.apiVersion` | API version of the referent. | Required if using `ref` |
|
|
| [`ref.kind`][kubernetes-kinds] | Kind of the referent. | Required if using `ref` |
|
|
| [`ref.namespace`][kubernetes-namespaces] | Namespace of the referent. If omitted this defaults to the object holding it. | Optional |
|
|
| [`ref.name`][kubernetes-names] | Name of the referent. | Required if using `ref` |
|
|
| `uri` | This can be an absolute URL with a non-empty scheme and non-empty host that points to the target or a relative URI. Relative URIs are resolved using the base URI retrieved from Ref. | Required if _not_ using `ref` |
|
|
|
|
!!! note
|
|
At least one of `ref` or `uri` is required. If both are specified, `uri` is
|
|
resolved into the URL from the Addressable `ref` result.
|
|
|
|
#### Example: Sink parameter
|
|
|
|
Given the following YAML, if `ref` resolves into
|
|
`"http://mysink.default.svc.cluster.local"`, then `uri` is added to this
|
|
resulting in `"http://mysink.default.svc.cluster.local/extra/path"`.
|
|
|
|
<!-- TODO we should have a page to point to describing the ref+uri destinations and the rules we use to resolve those and reuse the page. -->
|
|
|
|
```yaml
|
|
apiVersion: sources.knative.dev/v1
|
|
kind: ApiServerSource
|
|
metadata:
|
|
name: <apiserversource>
|
|
namespace: <namespace>
|
|
spec:
|
|
...
|
|
sink:
|
|
ref:
|
|
apiVersion: v1
|
|
kind: Service
|
|
namespace: default
|
|
name: mysink
|
|
uri: /extra/path
|
|
```
|
|
|
|
!!! contract
|
|
This results in the `K_SINK` environment variable being set on the sink container
|
|
as `"http://mysink.default.svc.cluster.local/extra/path"`.
|
|
|
|
|
|
### CloudEvent Overrides
|
|
|
|
CloudEvent Overrides defines overrides to control the output format and
|
|
modifications of the event sent to the sink.
|
|
|
|
A `ceOverrides` definition supports the following fields:
|
|
|
|
| Field | Description | Required or optional |
|
|
|-------|-------------|----------------------|
|
|
| `extensions` | Specifies which attributes are added or overridden on the outbound event. Each `extensions` key-value pair is set independently on the event as an attribute extension. | Optional |
|
|
|
|
!!! note
|
|
Only valid [CloudEvent attribute names][cloudevents-attribute-naming] are
|
|
allowed as extensions. You cannot set the spec defined attributes from
|
|
the extensions override configuration. For example, you can not modify the
|
|
`type` attribute.
|
|
|
|
#### Example: CloudEvent Overrides
|
|
|
|
```yaml
|
|
apiVersion: sources.knative.dev/v1
|
|
kind: ApiServerSource
|
|
metadata:
|
|
name: <apiserversource>
|
|
namespace: <namespace>
|
|
spec:
|
|
...
|
|
ceOverrides:
|
|
extensions:
|
|
extra: this is an extra attribute
|
|
additional: 42
|
|
```
|
|
|
|
!!! contract
|
|
This results in the `K_CE_OVERRIDES` environment variable being set on the
|
|
sink container as follows:
|
|
|
|
```json
|
|
{ "extensions": { "extra": "this is an extra attribute", "additional": "42" } }
|
|
```
|
|
|
|
[kubernetes-overview]:
|
|
https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
|
|
[kubernetes-kinds]:
|
|
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
|
|
[label-selectors]:
|
|
http://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
|
|
[kubernetes-names]:
|
|
https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
|
|
[kubernetes-namespaces]:
|
|
https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/
|
|
[cloudevents-attribute-naming]:
|
|
https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#attribute-naming-convention
|