Hook

This page describes how hook targets are defined in various APIs.

Each hook that you define as part of using one of the hook-based APIs has the following fields:

• Example
• Webhook
  • Service Reference
  • Etag Reference
  • CABundle Reference
    • Examples
  • Authorization Reference
    • Example
  • BasicAuth Reference
    • Example
  • ClientTLS Reference
    • Example
• Endpoint Configs

Example

webhook:
  url: http://my-controller-svc/sync

Webhook

Each Webhook has the following fields:

Service Reference

Within a webhook, the service field has the following subfields:

Etag Reference

More details in rfc7232.

Etag is a hash of response content, controller that supports etag notion should add "ETag" header to each 200 response. Metacontrollers that support "ETag" should send the "If-None-Match" header with value of ETag of cached content. If content has not changed, controller should reply with "304 Not modified" or "412 Precondition Failed", otherwise it sends 200 with "ETag" header.

This logic helps save traffic and CPU time on webhook processing.

Within a webhook, the eTag field has the following subfields:

Enabled             *bool  `json:"enabled,omitempty"`
CacheTimeoutSeconds *int32 `json:"cacheTimeoutSeconds,omitempty"`
CacheCleanupSeconds *int32 `json:"cacheCleanupSeconds,omitempty"`

CABundle Reference

The caBundle field configures the CA certificate(s) used to verify the TLS certificate presented by the webhook server. It is only needed when the webhook endpoint uses HTTPS with a private or self-signed CA. For publicly-trusted CAs (e.g. Let's Encrypt), omit this field entirely.

Exactly one of the following sources must be specified:

For both secretRef and configMapRef, the referenced object has the following subfields:

Examples

Inline PEM:

webhook:
  url: https://my-hook.my-ns:8443/sync
  caBundle:
    inline: |
      -----BEGIN CERTIFICATE-----
      MIIDxTCCAq2gAwIB...
      -----END CERTIFICATE-----

Secret reference:

webhook:
  url: https://my-hook.my-ns:8443/sync
  caBundle:
    secretRef:
      name: my-tls-secret # Secret of type kubernetes.io/tls
      namespace: my-ns
      key: ca.crt # optional; defaults to "ca.crt"

ConfigMap reference:

webhook:
  url: https://my-hook.my-ns:8443/sync
  caBundle:
    configMapRef:
      name: my-ca-bundle
      namespace: my-ns
      key: ca.crt # optional; defaults to "ca.crt"

Note on CA rotation: The CA bundle is resolved once when the controller CR is created or updated. If the referenced Secret or ConfigMap changes (e.g. due to certificate rotation), metacontroller will not automatically pick up the new value. To force a reload, update the controller CR (e.g. add or change an annotation) to trigger re-creation of the webhook executor.

Authorization Reference

The authorization field adds a token-based Authorization header to every webhook request. authorization and basicAuth are mutually exclusive — only one may be set per webhook or connection entry.

The type field sets the scheme prefix (e.g. Bearer, Token). // +kubebuilder:default="Bearer"

The secretRef sub-object has the following fields:

Example

webhook:
  url: https://my-hook.my-ns:8443/sync
  authorization:
    type: Bearer
    secretRef:
      name: my-token-secret
      namespace: my-ns
      key: token

BasicAuth Reference

The basicAuth field configures HTTP Basic Authentication. The username and password are read from a single Kubernetes Secret. basicAuth and authorization are mutually exclusive.

The secretRef sub-object has the following fields:

Example

webhook:
  url: https://my-hook.my-ns:8443/sync
  basicAuth:
    secretRef:
      name: my-basic-auth-secret
      namespace: my-ns
    usernameKey: username # optional; defaults to "username"
    passwordKey: password # optional; defaults to "password"

ClientTLS Reference

The clientTLS field configures a client certificate presented during the TLS handshake for mutual TLS (mTLS). It can be combined with any authentication method or used alone.

The secretRef sub-object has the following fields:

Example

webhook:
  url: https://my-hook.my-ns:8443/sync
  clientTLS:
    secretRef:
      name: my-client-tls-secret
      namespace: my-ns
    certKey: tls.crt # optional; defaults to "tls.crt"
    privateKeyKey: tls.key # optional; defaults to "tls.key"

Endpoint Configs

The endpointConfigs field on a CompositeController or DecoratorController lets you define per-host connection settings (CA bundle, client TLS, and authentication) that apply to all webhook hooks whose URL matches a given host. Per-hook fields (if any are set) fully override the matching endpointConfigs entry for that hook — there is no field-level merging.

spec:
  endpointConfigs:
    - host: my-hook.my-ns
      caBundle:
        secretRef:
          name: my-ca-secret
          namespace: my-ns
      authorization:
        secretRef:
          name: my-token-secret
          namespace: my-ns
          key: token

Each entry in endpointConfigs supports the following fields: