Skip to content

Latest commit

 

History

History
443 lines (214 loc) · 13.2 KB

api.md

File metadata and controls

443 lines (214 loc) · 13.2 KB
Raw

API Reference

Packages

eno.azure.io/v1

Resource Types

Binding

Bindings map a specific Kubernetes resource to a ref exposed by a synthesizer. Compositions use bindings to populate inputs supported by their synthesizer.

Appears in:

Field Description Default Validation
key string Key determines which ref this binding binds to. Opaque.
resource ResourceBinding

Composition

Compositions represent a collection of related, synthesized resources.

For example: when managing Postgres with Eno, one would create a composition per distinct instance of Postgres, all referencing a single synthesizer resource.

Changing the spec of a composition will result in re-synthesis.

Field Description Default Validation
apiVersion string eno.azure.io/v1
kind string Composition
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec CompositionSpec
status CompositionStatus

CompositionSpec

Appears in:

Field Description Default Validation
synthesizer SynthesizerRef Compositions are synthesized by a Synthesizer, referenced by name.
bindings Binding array Synthesizers can accept Kubernetes resources as inputs.
Bindings allow compositions to specify which resource to use for a particular input "reference".
Declaring extra bindings not (yet) supported by the synthesizer is valid.
synthesisEnv EnvVar array SynthesisEnv
A set of environment variables that will be made available inside the synthesis Pod.		 MaxItems: 500

CompositionStatus

Appears in:

Field Description Default Validation
simplified SimplifiedStatus
currentSynthesis Synthesis
previousSynthesis Synthesis
pendingResynthesis Time
inputRevisions InputRevisions array

EnvVar

Appears in:

Field Description Default Validation
name string MaxLength: 1000
value string

InputRevisions

Appears in:

Field Description Default Validation
key string
resourceVersion string
revision integer
synthesizerGeneration integer

PodOverrides

Appears in:

Field Description Default Validation
labels object (keys:string, values:string)
annotations object (keys:string, values:string)
resources ResourceRequirements

Ref

Ref defines a synthesizer input. Inputs are typed using the Kubernetes API - they are just normal Kubernetes resources. The consumer (synthesizer) specifies the resource's kind/group, while the producer (composition) specifies a specific resource name/namespace.

Compositions that use the synthesizer will be re-synthesized when the resource bound to this ref changes. Re-synthesis happens automatically while honoring the globally configured cooldown period.

Appears in:

Field Description Default Validation
key string Key corresponds to bindings to this ref.
resource ResourceRef
defer boolean Allows control over re-synthesis when inputs changed.
A non-deferred input will trigger a synthesis immediately, whereas a
deferred input will respect the cooldown period.

ResourceBinding

A reference to a specific resource name and optionally namespace.

Appears in:

Field Description Default Validation
name string
namespace string

ResourceRef

A reference to a resource kind/group.

Appears in:

Field Description Default Validation
group string
version string
kind string

Result

Appears in:

Field Description Default Validation
message string
severity string
tags object (keys:string, values:string)

SimplifiedStatus

Appears in:

Field Description Default Validation
status string
error string

Symphony

Symphony is a set of variations on a composition. Useful for creating several compositions that use a common set of bindings but different synthesizers.

This pattern is highly opinionated for use-cases in which a single "unit of management" includes multiple distinct components. For example: deploying many instances of an application that is comprised of several components (Wordpress, etc.).

Field Description Default Validation
apiVersion string eno.azure.io/v1
kind string Symphony
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec SymphonySpec
status SymphonyStatus

SymphonySpec

Appears in:

Field Description Default Validation
variations Variation array Each variation will result in the creation of a composition.
Synthesizer refs must be unique across variations.
Removing a variation will cause the composition to be deleted!
bindings Binding array Bindings are inherited by all compositions managed by this symphony.
synthesisEnv EnvVar array SynthesisEnv
Copied opaquely into the compositions managed by this symphony.		 MaxItems: 500

SymphonyStatus

Appears in:

Field Description Default Validation
observedGeneration integer
synthesized Time
reconciled Time
ready Time
synthesizers SynthesizerRef array

Synthesis

A synthesis is the result of synthesizing a composition. In other words: it's a collection of resources returned from a synthesizer.

Appears in:

Field Description Default Validation
uuid string A random UUID scoped to this particular synthesis operation.
Used internally for strict ordering semantics.
observedCompositionGeneration integer The value of the composition's metadata.generation at the time the synthesis began.
This is a min i.e. a newer composition may have been used.
observedSynthesizerGeneration integer The value of the synthesizer's metadata.generation at the time the synthesis began.
This is a min i.e. a newer composition may have been used.
initialized Time Initialized is set when the synthesis process is initiated.
podCreation Time Time at which the most recent synthesizer pod was created.
synthesized Time Time at which the synthesis completed i.e. resourceSlices was written
reconciled Time Time at which the synthesis's resources were reconciled into real Kubernetes resources.
ready Time Time at which the synthesis's reconciled resources became ready.
attempts integer Counter used internally to calculate back off when retrying failed syntheses.
results Result array Results are passed through opaquely from the synthesizer's KRM function.
inputRevisions InputRevisions array InputRevisions contains the versions of the input resources that were used for this synthesis.
deferred boolean Deferred is true when this synthesis was caused by a change to either the synthesizer
or an input with a ref that sets Defer == true.

Synthesizer

Synthesizers are any process that can run in a Kubernetes container that implements the KRM Functions Specification.

Synthesizer processes are given some metadata about the composition they are synthesizing, and are expected to return a set of Kubernetes resources. Essentially they generate the desired state for a set of Kubernetes resources.

Field Description Default Validation
apiVersion string eno.azure.io/v1
kind string Synthesizer
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec SynthesizerSpec
status SynthesizerStatus

SynthesizerRef

Appears in:

Field Description Default Validation
name string

SynthesizerSpec

Appears in:

Field Description Default Validation
image string Copied opaquely into the container's image property.
command string array Copied opaquely into the container's command property. [synthesize]
execTimeout Duration Timeout for each execution of the synthesizer command. 10s
podTimeout Duration Pods are recreated after they've existed for at least the pod timeout interval.
This helps close the loop in failure modes where a pod may be considered ready but not actually able to run.		 2m
reconcileInterval Duration Synthesized resources can optionally be reconciled at a given interval.
Per-resource jitter will be applied to avoid spikes in request rate.
refs Ref array Refs define the Synthesizer's input schema without binding it to specific
resources.
podOverrides PodOverrides PodOverrides sets values in the pods used to execute this synthesizer.

SynthesizerStatus

Appears in:

Variation

Appears in:

Field Description Default Validation
labels object (keys:string, values:string) Used to populate the composition's metadata.labels.
annotations object (keys:string, values:string) Used to populate the composition's medatada.annotations.
synthesizer SynthesizerRef Used to populate the composition's spec.synthesizer.
bindings Binding array Variation-specific bindings get merged with Symphony bindings and take
precedence over them.