Blueprint Bindings

A BlueprintBinding custom resource (CR) is used to automate the assignment of Kanister blueprints to applications. Once a BlueprintBinding is created, K10 will use it during snapshot, export and restore routines to automatically run a desired blueprint for matching workloads including workloads that are yet to be created in a cluster. You can learn more about Kanister blueprints in this section.

A BlueprintBinding consists of two parts: a reference to a Kanister blueprint and a resource selector. For resources that match the selector, K10 will automatically use the specified blueprint.

Warning

A BlueprintBinding has priority over blueprint annotations by default.
If a resource matches a BlueprintBinding and has a blueprint annotation at the same time, K10 will use the blueprint specified in the BlueprintBinding.

For complete documentation of the BlueprintBinding CR, refer to BlueprintBinding API Type.

Resource Selector

The resources portion of the blueprint binding spec indicates which kind of resources this blueprint binding will apply to.

Note

For resources that match multiple blueprint bindings, K10 will use the earliest created one.

For a resource to match the selector, it must meet all the requirements from matchAll and at least one requirement from matchAny (if any). A blueprint binding with no requirements is considered invalid.

Both matchAll and matchAny portions of resources represent a list of resource requirements to meet. A single resource requirement can set one of the following constraints:

  • type: selects resources by group, version and resource (GVR) values

  • namespace: selects resources by namespace

  • annotations: selects resources by annotations

  • labels: selects resources by labels

Example BlueprintBinding Operations

Create a Blueprint Binding

The following example illustrates how to create a blueprint binding which will automatically apply a blueprint to all statefulsets in the group apps that has no custom blueprint annotations.

$ cat > sample-blueprint-binding.yaml <<EOF
apiVersion: config.kio.kasten.io/v1alpha1
kind: BlueprintBinding
metadata:
  name: sample-blueprint-binding
  namespace: kasten-io
spec:
  blueprintRef:
    name: my-blueprint
    namespace: kasten-io
  resources:
    matchAll:
      - type:
          operator: In
          values:
            - group: apps
              resource: statefulsets
      - annotations:
          key: kanister.kasten.io/blueprint
          operator: DoesNotExist
EOF

$ kubectl apply -f sample-blueprint-binding.yaml
blueprintbinding.config.kio.kasten.io/sample-blueprint-binding created

# make sure it initializes and validates properly
$ kubectl get blueprintbindings.config.kio.kasten.io --namespace kasten-io -w
NAME                       DISABLED   STATUS    AGE
sample-blueprint-binding              Success   7s

Update a Blueprint Binding

To update a BlueprintBinding, edit the spec portion of a BlueprintBinding CR using your preferred method of submitting resource changes with kubectl. E.g. disabled: true can be added to the spec to disable the blueprint binding.

$ kubectl apply -f sample-blueprint-binding-changed.yaml
blueprintbinding.config.kio.kasten.io/sample-blueprint-binding configured

Once the change is submitted, K10 will re-validate the BlueprintBinding and update .status.validation accordingly.

$ kubectl get blueprintbindings.config.kio.kasten.io --namespace kasten-io -w
NAME                       DISABLED   STATUS    AGE
sample-blueprint-binding              Success   45s
sample-blueprint-binding   true       Success   47s

Delete a Blueprint Binding

You can delete a BlueprintBinding using the following command.

# delete blueprint binding "sample-blueprint-binding" for K10 installed in "kasten-io"
$ kubectl delete blueprintbindings.config.kio.kasten.io sample-blueprint-binding --namespace kasten-io
blueprintbinding.config.kio.kasten.io "sample-blueprint-binding" deleted

BlueprintBinding API Type

The following is a complete specification of the BlueprintBinding CR.

# Standard Kubernetes API Version declaration. Required.
apiVersion: config.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: BlueprintBinding
# Standard Kubernetes metadata. Required.
metadata:
  # BlueprintBinding name. May be any valid Kubernetes object name. Required.
  # BlueprintBinding name is not mutable once created.
  name: sample-blueprint-binding
  # BlueprintBinding names must be unique and as an alternative to name above
  # one can take advantage of Kubernetes auto name generation.
  generateName: blueprint-binding-
  # BlueprintBinding namespace. Required. Must be namespace where K10 is installed.
  namespace: kasten-io
# BlueprintBinding parameters. Required.
spec:
  # Disabled blueprint bindings are ignored by K10. Optional.
  # Default: false
  disabled: false
  # Blueprint to be used by BlueprintBinding. Required.
  blueprintRef:
    name: my-blueprint
    namespace: kasten-io
  # Resource selector for which the blueprint will be used. Required
  resources:
    # Array of resource requirements. Optional.
    # A resource must meet all of them to match the selector.
    # A resource requirement is a requirement for either type, namespace, annotations, or labels.
    # BlueprintBinding must have at least one requirement in matchAll or matchAny.
    matchAll:
      # Type selector requirement for group, version and resource (GVR). Optional.
      - type:
          # Operator represents a resource type's relationship to a set of values. Required.
          # Valid operators are In and NotIn.
          operator: In
          # Array of GVR values. Required.
          values:
            - group: apps
              version: v1
              resource: statefulsets
      # Namespace selector requirement. Optional.
      - namespace:
          # Operator represents a resource namespace's relationship to a set of values. Required.
          # Valid operators are In, NotIn, Exists and DoesNotExist.
          operator: In
          # Array of string values. Required if the operator is In or NotIn.
          # If the operator is Exists or DoesNotExist, the values array must be empty.
          values:
            - ns1
            - ns2
      # Annotation selector requirement that contains a key, values and an operator that
      # relates the key and values. Optional.
      - annotations:
          # Annotation name that the selector applies to. Required.
          key: kanister.kasten.io/blueprint
          # Operator represents a key's relationship to a set of values. Required.
          # Valid operators are In, NotIn, Exists and DoesNotExist.
          operator: NotIn
          # Array of string values. Required if the operator is In or NotIn.
          # If the operator is Exists or DoesNotExist, the values array must be empty.
          values:
            - "production-blueprint"
      # Annotation selector requirement that contains a key, values and an operator that
      # relates the key and values. Optional.
      - labels:
          # Label key that the selector applies to. Required.
          key: app
          # Operator represents a key's relationship to a set of values. Required.
          # Valid operators are In, NotIn, Exists and DoesNotExist.
          operator: In
          # Array of string values. Required if the operator is In or NotIn.
          # If the operator is Exists or DoesNotExist, the values array must be empty.
          values:
            - "myapp"
    # Array of resource requirements. Optional.
    # A resource must meet at least one of them to match the selector.
    # A resource requirement is a requirement for either type, namespace, annotations, or labels.
    # BlueprintBinding must have at least one requirement in matchAll or matchAny.
    matchAny:
      - # Array items have the same syntax as in matchAll
# Status of the BlueprintBinding. Users should not set any data here.
status:
  # Validation status of the BlueprintBinding
  # Valid values are:
  #   # Success - successfully initialized and validated
  #   # Failed - not properly initialized or validated
  # Only blueprint bindings which have status of Success
  # (and which are not disabled) will be used by the system
  validation: Success
  # An array of any validation or initialization errors encountered.
  error: null