bloxcd.dev/v1alpha1

Blox

A Blox fetches manifests from a source, renders them, and keeps them applied to one or more clusters.

apiVersion
bloxcd.dev/v1alpha1
kind
Blox
CRD
bloxes.bloxcd.dev
Resource
bloxes, short name bx
Scope
Namespaced
JSON Schema
blox_v1alpha1.json

Install the CRD

kubectl apply -f https://bloxcd.dev/crds/bloxes.bloxcd.dev.yaml

Validate in your editor

Add this first line to a Blox file. The YAML language server, used by VS Code, Neovim and others, then checks fields and completes them.

# yaml-language-server: $schema=https://bloxcd.dev/schemas/bloxcd.dev/blox_v1alpha1.json

Validate in CI

The schema follows the CRDs-catalog layout, so kubeconform finds it from the group, kind and version:

kubeconform -schema-location default \
  -schema-location 'https://bloxcd.dev/schemas/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  my-blox.yaml

spec

Fields you set

Every field has its own link, such as https://bloxcd.dev/v1alpha1/blox/#spec.source.git.url. Rules marked CEL are enforced by the API server.

spec.dependsOn []object

Other Blox objects that must be Ready before this one is applied.

spec.dependsOn[].name stringrequired

Defaults to the namespace of the depending Blox.

spec.interval stringdefault "5m"

How often to check the source and correct drift, e.g. 5m, 1h.

spec.notify []string

Notification sinks to tell when this Blox fails, recovers or applies a new revision. Sinks are named in bloxd's configuration by its admin.

spec.prune booleandefault false

Delete objects that disappear from the source (and everything on Blox deletion).

spec.render objectdefault {}

How to turn the source into manifests. Defaults to plain.

CEL set at most one of render.plain, render.kustomize or render.helm [has(self.plain), has(self.kustomize), has(self.helm)].filter(x, x).size() <= 1

Renders a Helm chart with helm template; blox applies the result like any other manifests (no Helm release storage, as in Argo CD). The chart comes from source.helm, or from a directory in source.git. The release namespace is spec.targetNamespace, or the Blox's own namespace.

Helm release name, used by most charts to name objects. Defaults to the Blox's name.

Inline chart values, merged over valuesFrom.

ConfigMaps or Secrets (in the Blox's namespace) holding values, merged in order.

CEL valuesFrom kind must be ConfigMap or Secret self.kind == 'ConfigMap' || self.kind == 'Secret'

ConfigMap or Secret.

Skip this reference if the object or key doesn't exist, instead of failing.

Key holding the values. Defaults to values.yaml.

Strategic-merge or JSON6902 patch, as in a kustomization.yaml.

Values for ${VAR} placeholders, applied after kustomize build.

spec.render.plain.substitute map[string]string

Values for ${VAR} placeholders in the manifests.

How soon to retry after a failure. Defaults to interval.

spec.rollout object

Roll changes out to the placed clusters wave by wave instead of all at once (needs bloxd --mode=hub and wait). A new revision or spec edit reaches a wave only once every cluster in the waves before it runs it and is healthy; a failure halts the rollout where it is.

How many clusters may be updating or failing at once. Defaults to 1.

Clusters in rollout order, by label. A cluster goes in the first wave that matches it; placed clusters matching none, and the hub's own cluster (which has no labels), form a last wave. {} matches all.

matchExpressions is a list of label selector requirements. The requirements are ANDed.

key is the label key that the selector applies to.

operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.

values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.

matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.

ServiceAccount (in this namespace) to impersonate when applying.

spec.source objectrequired

Where the manifests come from. Exactly one of git, oci or helm.

CEL exactly one of source.git, source.oci or source.helm must be set [has(self.git), has(self.oci), has(self.helm)].filter(x, x).size() == 1

Directory inside the repository to render. Defaults to the root.

spec.source.git.ref objectdefault {}

Which revision to check out. Defaults to the remote HEAD.

CEL set at most one of branch, tag, semver or commit [has(self.branch), has(self.tag), has(self.semver), has(self.commit)].filter(x, x).size() <= 1

Follow the tip of this branch, e.g. main.

Pin to this commit (full SHA-1).

Follow the highest tag in this semver range, as in Flux, e.g. >=1.4.0 <2.0.0, 1.x or ~1.4. Tags may have a v prefix. A bare version (1.4.2) matches only that version; pre-releases only match a range that names one.

Pin to this tag, e.g. v1.4.2.

Secret with username and password (or token) for HTTPS.

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

spec.source.git.url stringrequired

https:// repository URL. SSH isn't supported; use HTTPS with a read-only token (every forge offers one).

A chart from a Helm repository. Rendered with render.helm, which is implied and may be left out.

spec.source.helm.chart stringrequired

Chart name, e.g. podinfo.

spec.source.helm.repo stringrequired

Chart repository: https://… (with an index.yaml) or oci://registry/path.

Secret with username/password for the repository or registry.

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

Exact version or semver range, e.g. 6.7.0 or >=6.7.0 <7.0.0. Defaults to the latest.

Manifests packaged as an OCI artifact, in the format flux push artifact produces: one application/vnd.cncf.flux.content.v1.tar+gzip layer holding a directory tree.

CEL source.oci.url must start with oci:// self.url.startsWith('oci://')

Talk to the registry over plain HTTP. Only for registries inside the cluster.

Directory inside the artifact to render. Defaults to the root.

spec.source.oci.ref objectdefault {}

Which artifact to pull. Defaults to the latest tag.

CEL set at most one of tag, semver or digest [has(self.tag), has(self.semver), has(self.digest)].filter(x, x).size() <= 1

Pin to this manifest digest, e.g. sha256:f74f….

Pull the highest tag in this semver range, with the same syntax as source.git.ref.semver. Tags that aren't versions are ignored.

Pull this tag, e.g. 6.7.0.

Secret with username/password, or a kubernetes.io/dockerconfigjson Secret (as Flux uses) with an entry for the registry.

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

spec.source.oci.url stringrequired

Artifact repository, e.g. oci://ghcr.io/org/manifests/app (without a tag).

Refuse the artifact unless it carries a valid signature. Same shape as Flux's OCIRepository.spec.verify.

CEL verify.provider must be cosign (notation isn't supported yet) self.provider == 'cosign'

CEL verify needs a secretRef with cosign public keys, or matchOIDCIdentity for keyless signatures has(self.secretRef) || (has(self.matchOIDCIdentity) && size(self.matchOIDCIdentity) > 0)

Keyless (Sigstore Fulcio and Rekor): accept a signature whose certificate matches any of these identities.

The OIDC issuer, e.g. ^https://token\\.actions\\.githubusercontent\\.com$.

The certificate subject: a workflow URL or an email address.

spec.source.oci.verify.provider stringdefault "cosign"

Signature format. Only cosign so far.

Secret with cosign public keys: every key ending in .pub. A signature by any of them is accepted.

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

spec.suspend booleandefault false

Stop reconciling without deleting anything.

Put every namespaced object in this namespace, overriding what the manifests say. Same meaning as Flux's targetNamespace. The namespace must exist or be created by the source.

spec.targets []object

Which clusters to apply to. Defaults to the local cluster.

CEL set exactly one of local: true or clusterSelector self.local != has(self.clusterSelector)

Apply to every BloxCluster whose labels match (needs bloxd --mode=hub). An empty selector ({}) matches every cluster. A cluster matched by several targets gets the first one's overrides.

matchExpressions is a list of label selector requirements. The requirements are ANDed.

key is the label key that the selector applies to.

operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.

values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.

matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.

spec.targets[].local booleandefault false

Apply to the cluster bloxd runs in.

Per-target Kustomize patches, applied after render.kustomize.patches.

Strategic-merge or JSON6902 patch, as in a kustomization.yaml.

spec.targets[].substitute map[string]string

Per-target ${VAR} overrides, merged over the renderer's substitute (plain and kustomize renders).

Per-target Helm values, deep-merged over render.helm values.

spec.wait object

If set, Ready waits for every applied object to become healthy.

How long to wait for health before marking Ready=False. Defaults to 5m.

status

Fields bloxd reports

Written by the controller. Read them with blox status or kubectl get blox -o yaml.

status.clusters []object

Objects applied to this cluster, for clusters the hub applies to directly. The local cluster's are in status.inventory.

Applied objects. Moves to a ConfigMap (see configMapRef) once large (RFC §5.3).

Hash of the Helm install/upgrade hook objects (helm.sh/hook) that were last run. Hooks run again only when this changes, so a Job deleted after it finished isn't started a second time.

status.clusters[].name stringrequired
status.clusters[].objects integerrequired
status.clusters[].ready booleanrequired

With spec.rollout: a fingerprint of the spec and revision last applied here, to tell which clusters a rollout has reached.

Revision currently applied on this cluster.

status.conditions[].lastTransitionTime string (date-time)required

lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

message is a human readable message indicating details about the transition. This may be an empty string.

observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

status of the condition, one of True, False, Unknown.

status.conditions[].type stringrequired

type of condition in CamelCase or in foo.example.com/CamelCase.

status.inventory.count integerrequired

Applied objects. Moves to a ConfigMap (see configMapRef) once large (RFC §5.3).

Hash of the Helm install/upgrade hook objects (helm.sh/hook) that were last run. Hooks run again only when this changes, so a Job deleted after it finished isn't started a second time.

Revision whose manifests are currently applied, e.g. main@sha1:5e1a2c9.

Revision of the most recent attempt, successful or not.

Last bloxcd.dev/reconcile-requested-at value that was handled.

Progress of spec.rollout.

status.rollout.clusters integerrequired

Placed clusters.

status.rollout.revision stringrequired

The revision being rolled out, or last rolled out.

status.rollout.updated integerrequired

Clusters that run the latest spec and revision and are healthy.

Wave in progress, counting from 1. Unset once every wave is done.

status.rollout.waves integerrequired

Number of waves with placed clusters in them.

Example

podinfo from Git, rendered with Kustomize

# yaml-language-server: $schema=https://bloxcd.dev/schemas/bloxcd.dev/blox_v1alpha1.json
# Deploys podinfo from its upstream kustomize overlay.
#   blox crds | kubectl apply -f -
#   kubectl create namespace apps && kubectl apply -f examples/podinfo.yaml
#   blox status -n apps podinfo
apiVersion: bloxcd.dev/v1alpha1
kind: Blox
metadata:
  name: podinfo
  namespace: apps
spec:
  interval: 5m
  source:
    git:
      url: https://github.com/stefanprodan/podinfo
      ref: { tag: "6.7.0" }
      path: ./kustomize
  render:
    kustomize:
      patches:
        - target: { kind: HorizontalPodAutoscaler, name: podinfo }
          patch: |
            - op: replace
              path: /spec/minReplicas
              value: 1
  targets:
    - local: true
  prune: true
  wait:
    timeout: 3m