synthesizer-api.md

Synthesizer API

Synthesizers are container images that implement the KRM Functions API.

Here's a trivial example using bash.

apiVersion: eno.azure.io/v1
kind: Synthesizer
metadata:
  name: example
spec:
  image: docker.io/ubuntu:latest
  command:
  - /bin/bash
  - -c
  - |
    echo '
      {
        "apiVersion":"config.kubernetes.io/v1",
        "kind":"ResourceList",
        "items":[
          {
            "apiVersion":"v1",
            "kind":"ConfigMap",
            "metadata":{
              "name":"some-config",
              "namespace": "default"
            }
          }
        ]
      }'

Logging

The synthesizer process's stderr is piped to the synthesizer container it's running in so any typical log forwarding infra can be used.

Error Handling

The KRM API supports "results", which are a kind of metadata related to the execution process that would not otherwise be reflected in the generated resources. Each result has a severity of info, warning, or error. Eno currently supports only the error severity.

Functions that produce one or more results with severity == error will cause the resulting synthesis to be marked as failed. Failed syntheses will not be retried until they or their synthesizer are modified.

apiVersion: eno.azure.io/v1
kind: Synthesizer
metadata:
  name: error-example
spec:
  image: docker.io/ubuntu:latest
  command:
  - /bin/bash
  - -c
  - |
    echo '
      {
        "apiVersion":"config.kubernetes.io/v1",
        "kind":"ResourceList",
        "results": [{
          "severity": "error",
          "message": "The system is down, the system is down"
        }]
      }'

Here's the result:

$ kubectl get compositions
NAME      SYNTHESIZER     AGE   STATUS     ERROR
example   error-example   10s   NotReady   The system is down, the system is down

Merge Semantics / Drift Detection

Eno's reconciler keeps objects in sync with the state defined by the synthesizer. This is true when the resource itself changes (drift) or the expected state produced by the synthesizer changes.

Eno uses strategic three-way merge when possible, falling back to non-strategic three-way merge otherwise. All properties specified in Eno's expected state will always converge i.e. Eno will continue to patch the resource until it matches the expected state. However, other clients are free to set properties not defined by synthesizers without being "stomped on" by Eno.

Reconciliation Interval

By default, configuration drift will only be corrected when the expected state changes or the Eno reconciler process restarts. In most cases, resources produced by synthesizers should include an annotation to specify an interval at which drift can be corrected.

annotations:
  eno.azure.io/reconcile-interval: "15m" # supports any value parsable by Go's `time.ParseDuration`

Disable Updates

In cases where resources are expected to be modified by other clients, patches can be disabled by setting this annotation on resources generated by synthesizers:

annotations:
  eno.azure.io/disable-updates: "true"