Distributions API

A Distribution is a custom resource (CR) that is used to distribute Global Resources to clusters in a Multi-Cluster setup.

Additional information can be found on the Distributions page and the Global Resources page.

Example Distribution Operations

Create Distribution

The following example illustrates how to create a distribution that distributes a global policy and corresponding profile. The distribution and global resources are all defined in the kasten-io-mc namespace.

$ cat > sample-distribution.yaml <<EOF
apiVersion: dist.kio.kasten.io/v1alpha1
kind: Distribution
metadata:
  name: sample-dist
  namespace: kasten-io-mc
spec:
  clusters:
  - name: cluster2
  - name: cluster3
  sources:
  - ref:
      apiVersion: config.kio.kasten.io/v1alpha1
      kind: Policy
      name: sample-policy
      namespace: kasten-io-mc
  - ref:
      apiVersion: config.kio.kasten.io/v1alpha1
      kind: Profile
      name: sample-profile
      namespace: kasten-io-mc
EOF

$ kubectl apply -f sample-distribution.yaml
distribution.dist.kio.kasten.io/sample-dist created

Note

Although secrets may be added to a distribution as well, secrets referenced by a profile will be automatically discovered and distributed with the profile.

Distribution API Type

The following is a complete specification of the Distribution CR.

## Required Kubernetes resource information
apiVersion: dist.kio.kasten.io/v1alpha1
kind: Distribution

## Required Kubernetes metadata
## - name cannot be changed once created
## - namespace should be the Multi-Cluster namespace: 'kasten-io-mc'
metadata:
  name: sample-dist
  namespace: kasten-io-mc

## Distribution specification (required)
spec:
  ## List of cluster selectors used as distribution targets (optional)
  #
  ## Although the list of clusters selectors is optional, no distribution will
  ## take place unless at least one cluster is specified.
  #
  ## Each cluster selector specifies either a 'name' or a 'selector'.
  clusters:
    ## Name specifies the name of the cluster to target (optional)
  - name: my-cluster-name

    ## Label selector to select multiple clusters at once (optional)
  - selector: my-label in (one, two, three)

    ## An empty selector selects all clusters
  - selector: ""

  ## List of resources used as distribution sources (optional)
  #
  ## Although the list of sources is optional, no distribution will take place
  ## unless at least one resource is specified.
  sources:
    ## Kubernetes resource reference (optional)
  - ref:
      ## Kubernetes API group and version of the resource (required)
      apiVersion: config.kio.kasten.io/v1alpha1
      ## Kubernetes Kind of the resource (required)
      kind: Policy
      ## Kubernetes Name of the resource (required)
      name: sample-policy
      ## Kubernetes Namespace of the resource (required)
      namespace: kasten-io-mc

  ## A marker used to indicate that all previously distributed objects are
  ## stale and should be re-distributed.
  #
  ## Any arbitrary value may be used, as long as it differs from the previous
  ## value. A blank value is ignored, but may be used to "reset" the marker.
  invalidationMarker: i8y92

## Distribution status
status:
  ## Standard Kubernetes conditions. For additional information see:
  ## - https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Condition
  ## - https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1623-standardize-conditions
  conditions:
    ## The type "InSync" indicates whether the distribution has finished
    ## distributing objects.
  - type: InSync
    status: "True"
    reason: InSync
    message: All objects have been synchronized
    observedGeneration: 5
    lastTransitionTime: "2020-11-13T00:22:19Z"

    ## The type "Progressing" indicates whether the distribution is continuing
    ## to make progress or has become stuck (i.e. erroring).
  - type: Progressing
    status: "True"
    reason: InSync
    message: All objects have been synchronized
    observedGeneration: 5
    lastTransitionTime: "2020-11-11T18:54:27Z"

  ## A distributed object represents the state of a target resource in a given
  ## cluster.
  distributedObjects:
    ## The target resource information.
  - object:
      apiVersion: config.kio.kasten.io/v1alpha1
      kind: Policy
      name: sample-policy
      namespace: kasten-io

    ## Information about the source resource.
    #
    ## This information is used to detect changes to the source resource. The
    ## generation is used, if available, otherwise resource version is used.
    sourceInfo:
      uid: 0d038e42-2c74-4146-9430-1fd63aea9ebc
      generation: 8
      resourceVersion: "912381"

    ## The target cluster information for the distributed object.
    #
    ## The cluster ID is used to detect a target cluster being replaced.
    targetCluster:
      id: 4830058d-f93b-4531-894c-10a9d901f5f7
      name: my-cluster-name

    ## Whether the object is stale and needs to be re-distributed.
    stale: True

  ## The last recorded invalidation marker.
  #
  ## Used to detect changes in the invalidation marker.
  lastInvalidationMarker: i8y92