Skip to content

api.adoc

Latest commit

 

History

History
734 lines (514 loc) · 34.7 KB

api.adoc

File metadata and controls

734 lines (514 loc) · 34.7 KB
Raw

API Reference

espejote.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the espejote.io v1alpha1 API group

Admission

Admission is the Schema for the Admissions API. Admission currently fully relies on cert-manager for certificate management and webhook certificate injection. See the kustomize overlays for more information.

Field Description Default Validation

apiVersion string

espejote.io/v1alpha1

kind string

Admission

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

AdmissionSpec

AdmissionSpec defines the desired state of Admission.

Appears In:
Field Description Default Validation

webhookConfiguration WebhookConfiguration

WebhookConfiguration defines the configuration for the Admission webhook.
Allows fine grained control over what is forwarded to the webhook.
Note that Admission enforces namespace isolation. The namespaceSelector field is set to the namespace of the Admission and can’t be overridden.
The rules are enforced to only match namespaced resources.
Use ClusterAdmission for cluster scoped webhooks and resources.

mutating boolean

Mutating defines if the Admission should create a MutatingWebhookConfiguration or a ValidatingWebhookConfiguration.

template string

Template contains the Jsonnet code to decide the admission result.
Admission responses should be created using the espejote.libsonnet library.
esp.ALPHA.admission.allowed("Nice job!"), esp.ALPHA.admission.denied("Bad job!"), esp.ALPHA.admission.patched("added user annotation", [jsonPatchOp("add", "/metadata/annotations/user", "tom")]) are examples of valid responses.
The template can reference JsonnetLibrary objects by importing them.
JsonnetLibrary objects have the following structure:
- "espejote.libsonnet": The built in library for accessing the context and trigger information.
- "lib/<NAME>/<KEY>" libraries in the shared library namespace. The name corresponds to the name of the JsonnetLibrary object and the key to the key in the data field.
The namespace is configured at controller startup and normally points to the namespace of the controller.
- "<NAME>/<KEY>" libraries in the same namespace as the Admission. The name corresponds to the name of the JsonnetLibrary object and the key to the key in the data field.

ApplyOptions

Appears In:
Field Description Default Validation

fieldManager string

FieldManager is the field manager to use when applying the ManagedResource
If not set, the field manager is set to the name of the resource with managed-resource prefix

Optional: \{}

force boolean

Force is going to "force" Apply requests. It means user will
re-acquire conflicting fields owned by other people.

false

Optional: \{}

fieldValidation string

fieldValidation instructs the managed resource on how to handle
objects containing unknown or duplicate fields. Valid values are:
- Ignore: This will ignore any unknown fields that are silently
dropped from the object, and will ignore all but the last duplicate
field that the decoder encounters.
Note that Jsonnet won’t allow you to add duplicate fields to an object
and most unregistered fields will error out in the server-side apply
request, even with this option set.
- Strict: This will fail the request with a BadRequest error if
any unknown fields would be dropped from the object, or if any
duplicate fields are present. The error returned will contain
all unknown and duplicate fields encountered.
Defaults to "Strict".

Strict

Enum: [Ignore Strict]
Optional: \{}

ClusterAdmission

ClusterAdmission is the Schema for the ClusterAdmissions API. ClusterAdmission currently fully relies on cert-manager for certificate management and webhook certificate injection. See the kustomize overlays for more information.

Field Description Default Validation

apiVersion string

espejote.io/v1alpha1

kind string

ClusterAdmission

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

ClusterAdmissionSpec

ClusterAdmissionSpec defines the desired state of ClusterAdmission.

Appears In:
Field Description Default Validation

WebhookConfiguration defines the configuration for the Admission webhook.
Allows fine grained control over what is forwarded to the webhook.

mutating boolean

Mutating defines if the Admission should create a MutatingWebhookConfiguration or a ValidatingWebhookConfiguration.

template string

Template contains the Jsonnet code to decide the admission result.
Admission responses should be created using the espejote.libsonnet library.
esp.ALPHA.admission.allowed("Nice job!"), esp.ALPHA.admission.denied("Bad job!"), esp.ALPHA.admission.patched("added user annotation", [jsonPatchOp("add", "/metadata/annotations/user", "tom")]) are examples of valid responses.
The template can reference JsonnetLibrary objects by importing them.
JsonnetLibrary objects have the following structure:
- "espejote.libsonnet": The built in library for accessing the context and trigger information.
- "lib/<NAME>/<KEY>" libraries in the shared library namespace. The name corresponds to the name of the JsonnetLibrary object and the key to the key in the data field.
The namespace is configured at controller startup and normally points to the namespace of the controller.
Note that ClusterAdmission cannot reference non-library JsonnetLibrary objects.

ContextResource

Field Description Default Validation

apiVersion string

APIVersion of the resource that should be added to the context.
The APIVersion can be in the form "group/version" or "version".

kind string

Kind of the resource that should be added to the context.

name string

Name of the resource that should be added to the context.
If not set, all resources of the specified Kind are added to the context.

namespace string

Namespace for the resources that should be added to the context.
If not set, the namespace of the ManagedResource is used.
Can be set to empty string to add all namespaces.

labelSelector LabelSelector

LabelSelector can be used to filter the resources that should be added to the context.
This is efficiently done by the Kubernetes API server

matchNames string array

MatchNames can be used to filter the resources that should be added to the context.
This is considered experimental and might be removed in the future.
The filtering is done on the controller side and might not be as efficient as the LabelSelector.
Filtered objects are dropped before any caching or processing.

ignoreNames string array

IgnoreNames can be used to filter the resources that should be added to the context.
This is considered experimental and might be removed in the future.
The filtering is done on the controller side and might not be as efficient as the LabelSelector.
Filtered objects are dropped before any caching or processing.

stripManagedFields boolean

StripManagedFields removes the managedFields from the watched resource.
managedFields are not used in Espejote and if the template does not use them, they can be removed to significantly reduce the size of cached objects.
Defaults to true if not set.

Optional: \{}

JsonnetLibrary

JsonnetLibrary is the Schema for the jsonnetlibraries API.

Field Description Default Validation

apiVersion string

espejote.io/v1alpha1

kind string

JsonnetLibrary

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

JsonnetLibrarySpec

JsonnetLibrarySpec defines the desired state of JsonnetLibrary.

Appears In:
Field Description Default Validation

data object (keys:string, values:string)

Data is a map of Jsonnet library files.
The key is the file name and the value is the file content.
JsonnetLibraries can use relative imports as follows:

  • ./KEY and KEY resolve to the same JsonnetLibrary manifest.

  • ./NAME/KEY and NAME/KEY resolve to the same namespace (shared/local).

  • espejote.libsonnet always resolves to the built-in library.

  • ./espejote.libsonnet ` resolves to the `espejote.libsonnet key in the same library.

ManagedResource

ManagedResource is the Schema for the ManagedResources API

Field Description Default Validation

apiVersion string

espejote.io/v1alpha1

kind string

ManagedResource

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

ManagedResourceContext

Appears In:
Field Description Default Validation

name string

Name is the name of the context definition. The context can be referenced in the template by this name.

MinLength: 1

resource ContextResource

Resource defines the resource that should be added to the context.
Adds a list of zero or more resources to the context.

ManagedResourceSpec

ManagedResourceSpec defines the desired state of ManagedResource

Appears In:
Field Description Default Validation

triggers ManagedResourceTrigger array

Triggers define the resources that trigger the reconciliation of the ManagedResource
Trigger information will be injected when rendering the template.
This can be used to only partially render the template based on the trigger.

Optional: \{}

context ManagedResourceContext array

Context defines the context for the ManagedResource

serviceAccountRef LocalObjectReference

ServiceAccountRef is the service account this managed resource runs as.
The service account must have the necessary permissions to manage the resources referenced in the template.
If not set, the namespace’s default service account is used.

{ name:default }

template string

Template defines the template for the ManagedResource
The template is rendered using Jsonnet and the result is applied to the cluster.
The template can reference the context and trigger information.
All access to injected data should be done through the espejote.libsonnet import.
The template can reference JsonnetLibrary objects by importing them.
JsonnetLibrary objects have the following structure:
- "espejote.libsonnet": The built in library for accessing the context and trigger information.
- "lib/<NAME>/<KEY>" libraries in the shared library namespace. The name corresponds to the name of the JsonnetLibrary object and the key to the key in the data field.
The namespace is configured at controller startup and normally points to the namespace of the controller.
- "<NAME>/<KEY>" libraries in the same namespace as the ManagedResource. The name corresponds to the name of the JsonnetLibrary object and the key to the key in the data field.
The template can return a single object, a list of objects, or null. Everything else is considered an error.
If a list is returned, null objects in this list are silently dropped.
Namespaced objects default to the namespace of the ManagedResource.

cacheSyncTimeout Duration

CacheSyncTimeout defines the maximum time to wait for the initial sync of the context and trigger caches to complete.
If the initial sync does not complete within this time, the ManagedResource is marked as failed.
This usually happens because of missing RBAC permissions.
After the initial sync, the ManagedResource is reconciled normally.
Defaults to 2 minutes.

Format: duration
Optional: \{}

applyOptions ApplyOptions

ApplyOptions defines the options for applying the ManagedResource

ManagedResourceStatus

ManagedResourceStatus defines the observed state of ManagedResource

Appears In:
Field Description Default Validation

status string

Status reports the last overall status of the ManagedResource
More information can be found by inspecting the ManagedResource’s events with either kubectl describe or kubectl get events.

ManagedResourceTrigger

Appears In:
Field Description Default Validation

name string

Name is the name of the trigger. The trigger can be referenced in the template by this name.

MinLength: 1

interval Duration

Interval defines the interval at which the ManagedResource should be reconciled.

Format: duration

watchResource TriggerWatchResource

WatchResource defines one or multiple resources that trigger the reconciliation of the ManagedResource.
Resource information is injected when rendering the template and can be retrieved using (import "espejote.libsonnet").getTrigger().
local esp = import "espejote.libsonnet"; esp.triggerType() == esp.TriggerTypeWatchResource will be true if the render was triggered by a definition in this block.

Optional: \{}

watchContextResource WatchContextResource

WatchContextResource works the same as WatchResource, but it uses and already existing context resource.
This is useful when you require both full (when the template changes) and partial (a context resource changes) reconciliation of the same resource.
Check the example below. Both a context resource and a trigger are defined. If the trigger is not known in the template all network policies are reconciled.
If the trigger is known, only the network policies that match the trigger are reconciled. Using watchContextResource allows this without having to define the same resource again.

apiVersion: espejote.io/v1alpha1
kind: ManagedResource
metadata:
name: naemspace-default-netpol
annotations:
description: |
Injects a default network policy into every namespace not labeled netpol.example.com/no-default.
spec:
context:
- name: namespaces
resource:
apiVersion: v1
kind: Namespace
labelSelector:
matchExpressions:
- key: netpol.example.com/no-default
operator: DoesNotExist
triggers:
- name: namespace
watchContextResource:
name: namespaces
template: |
local esp = import 'espejote.libsonnet';

local netpolForNs = function(ns) {
[…​]
};

if esp.triggerName() == 'namespace' then [
netpolForNs(esp.triggerData().resource),
] else [
netpolForNs(ns)
for ns in esp.context().namespaces
]

TriggerWatchResource

Field Description Default Validation

apiVersion string

APIVersion of the resource that should be watched.
The APIVersion can be in the form "group/version" or "version".

kind string

Kind of the resource that should be watched.

name string

Name of the resource that should be watched.
If not set, all resources of the specified Kind are watched.

namespace string

Namespace for the resources that should be watched.
If not set, the namespace of the ManagedResource is used.
Can be explicitly set to empty string to watch all namespaces.

labelSelector LabelSelector

LabelSelector can be used to filter the resources that should be watched.
This is efficiently done by the Kubernetes API server

matchNames string array

MatchNames can be used to filter the resources that should be watched.
This is considered experimental and might be removed in the future.
The filtering is done on the controller side and might not be as efficient as the LabelSelector.
Filtered objects are dropped before any caching or processing.

ignoreNames string array

IgnoreNames can be used to filter the resources that should be watched.
This is considered experimental and might be removed in the future.
The filtering is done on the controller side and might not be as efficient as the LabelSelector.
Filtered objects are dropped before any caching or processing.

stripManagedFields boolean

StripManagedFields removes the managedFields from the watched resource.
managedFields are not used in Espejote and if the template does not use them, they can be removed to significantly reduce the size of cached objects.
Defaults to true if not set.

Optional: \{}

WatchContextResource

Field Description Default Validation

name string

Name is the name of the context definition used when creating this trigger.

WebhookConfiguration

Field Description Default Validation

rules RuleWithOperations array

Rules describes what operations on what resources/subresources the webhook cares about.
The webhook cares about an operation if it matches any Rule.
However, in order to prevent ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks
from putting the cluster in a state which cannot be recovered from without completely
disabling the plugin, ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks are never called
on admission requests for ValidatingWebhookConfiguration and MutatingWebhookConfiguration objects.

failurePolicy FailurePolicyType

FailurePolicy defines how unrecognized errors from the admission endpoint are handled -
allowed values are Ignore or Fail. Defaults to Fail.

Optional: \{}

matchPolicy MatchPolicyType

matchPolicy defines how the "rules" list is used to match incoming requests.
Allowed values are "Exact" or "Equivalent".

  • Exact: match a request only if it exactly matches a specified rule.
    For example, if deployments can be modified via apps/v1, apps/v1beta1, and extensions/v1beta1,
    but "rules" only included apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"],
    a request to apps/v1beta1 or extensions/v1beta1 would not be sent to the webhook.

  • Equivalent: match a request if modifies a resource listed in rules, even via another API group or version.
    For example, if deployments can be modified via apps/v1, apps/v1beta1, and extensions/v1beta1,
    and "rules" only included apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"],
    a request to apps/v1beta1 or extensions/v1beta1 would be converted to apps/v1 and sent to the webhook.

Defaults to "Equivalent"

Optional: \{}

objectSelector LabelSelector

ObjectSelector decides whether to run the webhook based on if the
object has matching labels. objectSelector is evaluated against both
the oldObject and newObject that would be sent to the webhook, and
is considered to match if either object matches the selector. A null
object (oldObject in the case of create, or newObject in the case of
delete) or an object that cannot have labels (like a
DeploymentRollback or a PodProxyOptions object) is not considered to
match.
Use the object selector only if the webhook is opt-in, because end
users may skip the admission webhook by setting the labels.
Default to the empty LabelSelector, which matches everything.

Optional: \{}

reinvocationPolicy ReinvocationPolicyType

reinvocationPolicy indicates whether this webhook should be called multiple times as part of a single admission evaluation.
Allowed values are "Never" and "IfNeeded".

Never: the webhook will not be called more than once in a single admission evaluation.

IfNeeded: the webhook will be called at least one additional time as part of the admission evaluation
if the object being admitted is modified by other admission plugins after the initial webhook call.
Webhooks that specify this option must be idempotent, able to process objects they previously admitted.
Note:
* the number of additional invocations is not guaranteed to be exactly one.
* if additional invocations result in further modifications to the object, webhooks are not guaranteed to be invoked again.
* webhooks that use this option may be reordered to minimize the number of additional invocations.
* to validate an object after all mutations are guaranteed complete, use a validating admission webhook instead.

Defaults to "Never".

Optional: \{}

matchConditions MatchCondition array

MatchConditions is a list of conditions that must be met for a request to be sent to this
webhook. Match conditions filter requests that have already been matched by the rules,
namespaceSelector, and objectSelector. An empty list of matchConditions matches all requests.
There are a maximum of 64 match conditions allowed.

The exact matching logic is (in order):
1. If ANY matchCondition evaluates to FALSE, the webhook is skipped.
2. If ALL matchConditions evaluate to TRUE, the webhook is called.
3. If any matchCondition evaluates to an error (but none are FALSE):
- If failurePolicy=Fail, reject the request
- If failurePolicy=Ignore, the error is ignored and the webhook is skipped

Optional: \{}

WebhookConfigurationWithNamespaceSelector

Appears In:
Field Description Default Validation

namespaceSelector LabelSelector

NamespaceSelector decides whether to run the webhook on an object based
on whether the namespace for that object matches the selector. If the
object itself is a namespace, the matching is performed on
object.metadata.labels. If the object is another cluster scoped resource,
it never skips the webhook.

For example, to run the webhook on any objects whose namespace is not
associated with "runlevel" of "0" or "1"; you will set the selector as
follows:
"namespaceSelector": {
"matchExpressions": [
{
"key": "runlevel",
"operator": "NotIn",
"values": [
"0",
"1"
]
}
]
}

If instead you want to only run the webhook on any objects whose
namespace is associated with the "environment" of "prod" or "staging";
you will set the selector as follows:
"namespaceSelector": {
"matchExpressions": [
{
"key": "environment",
"operator": "In",
"values": [
"prod",
"staging"
]
}
]
}

Default to the empty LabelSelector, which matches everything.

Optional: \{}

rules RuleWithOperations array

Rules describes what operations on what resources/subresources the webhook cares about.
The webhook cares about an operation if it matches any Rule.
However, in order to prevent ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks
from putting the cluster in a state which cannot be recovered from without completely
disabling the plugin, ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks are never called
on admission requests for ValidatingWebhookConfiguration and MutatingWebhookConfiguration objects.

failurePolicy FailurePolicyType

FailurePolicy defines how unrecognized errors from the admission endpoint are handled -
allowed values are Ignore or Fail. Defaults to Fail.

Optional: \{}

matchPolicy MatchPolicyType

matchPolicy defines how the "rules" list is used to match incoming requests.
Allowed values are "Exact" or "Equivalent".

  • Exact: match a request only if it exactly matches a specified rule.
    For example, if deployments can be modified via apps/v1, apps/v1beta1, and extensions/v1beta1,
    but "rules" only included apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"],
    a request to apps/v1beta1 or extensions/v1beta1 would not be sent to the webhook.

  • Equivalent: match a request if modifies a resource listed in rules, even via another API group or version.
    For example, if deployments can be modified via apps/v1, apps/v1beta1, and extensions/v1beta1,
    and "rules" only included apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"],
    a request to apps/v1beta1 or extensions/v1beta1 would be converted to apps/v1 and sent to the webhook.

Defaults to "Equivalent"

Optional: \{}

objectSelector LabelSelector

ObjectSelector decides whether to run the webhook based on if the
object has matching labels. objectSelector is evaluated against both
the oldObject and newObject that would be sent to the webhook, and
is considered to match if either object matches the selector. A null
object (oldObject in the case of create, or newObject in the case of
delete) or an object that cannot have labels (like a
DeploymentRollback or a PodProxyOptions object) is not considered to
match.
Use the object selector only if the webhook is opt-in, because end
users may skip the admission webhook by setting the labels.
Default to the empty LabelSelector, which matches everything.

Optional: \{}

reinvocationPolicy ReinvocationPolicyType

reinvocationPolicy indicates whether this webhook should be called multiple times as part of a single admission evaluation.
Allowed values are "Never" and "IfNeeded".

Never: the webhook will not be called more than once in a single admission evaluation.

IfNeeded: the webhook will be called at least one additional time as part of the admission evaluation
if the object being admitted is modified by other admission plugins after the initial webhook call.
Webhooks that specify this option must be idempotent, able to process objects they previously admitted.
Note:
* the number of additional invocations is not guaranteed to be exactly one.
* if additional invocations result in further modifications to the object, webhooks are not guaranteed to be invoked again.
* webhooks that use this option may be reordered to minimize the number of additional invocations.
* to validate an object after all mutations are guaranteed complete, use a validating admission webhook instead.

Defaults to "Never".

Optional: \{}

matchConditions MatchCondition array

MatchConditions is a list of conditions that must be met for a request to be sent to this
webhook. Match conditions filter requests that have already been matched by the rules,
namespaceSelector, and objectSelector. An empty list of matchConditions matches all requests.
There are a maximum of 64 match conditions allowed.

The exact matching logic is (in order):
1. If ANY matchCondition evaluates to FALSE, the webhook is skipped.
2. If ALL matchConditions evaluate to TRUE, the webhook is called.
3. If any matchCondition evaluates to an error (but none are FALSE):
- If failurePolicy=Fail, reject the request
- If failurePolicy=Ignore, the error is ignored and the webhook is skipped

Optional: \{}