bloxcd.dev/v1alpha1

BloxCluster

A BloxCluster registers a member cluster with a blox hub. Blox targets select clusters by their labels.

apiVersion
bloxcd.dev/v1alpha1
kind
BloxCluster
CRD
bloxclusters.bloxcd.dev
Resource
bloxclusters, short name bxc
Scope
Cluster
JSON Schema
bloxcluster_v1alpha1.json

Install the CRD

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

Validate in your editor

Add this first line to a BloxCluster 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/bloxcluster_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/bloxcluster/#spec.source.git.url. Rules marked CEL are enforced by the API server.

spec.connection objectrequired

How the hub reaches this cluster. Exactly one of agent or kubeconfigSecretRef.

CEL set exactly one of connection.agent or connection.kubeconfigSecretRef has(self.agent) != has(self.kubeconfigSecretRef)

The cluster runs bloxd --mode=agent, which connects to the hub (recommended).

The hub applies to the cluster directly with this kubeconfig (push mode).

Key holding the kubeconfig. Defaults to value, as Cluster API writes it.

status

Fields bloxd reports

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

Version of bloxd running as this cluster's agent.

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.

Kubernetes version of the member cluster, e.g. v1.34.1.

status.lastHeartbeat string (date-time)

When the hub last heard from the cluster.

Example

podinfo from Git, rendered with Kustomize

# yaml-language-server: $schema=https://bloxcd.dev/schemas/bloxcd.dev/bloxcluster_v1alpha1.json
# Registers a member cluster with a hub (bloxd --mode=hub). Blox targets
# select clusters by these labels; see examples/podinfo-fleet.yaml.
#
# Push mode: the hub applies with a kubeconfig stored in a Secret. The
# kubeconfig must use a token or client certificate (no exec plugins).
#   kubectl -n blox-system create secret generic eu-west-prod-1-kubeconfig \
#     --from-file=value=./eu-west-prod-1.kubeconfig
apiVersion: bloxcd.dev/v1alpha1
kind: BloxCluster
metadata:
  name: eu-west-prod-1
  labels:
    env: prod
    region: eu-west
spec:
  connection:
    kubeconfigSecretRef:
      name: eu-west-prod-1-kubeconfig
      namespace: blox-system