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