Usage

Once the kubensync operator is installed, you can start using it by defining custom resources (CRs) that specify the resources you want to synchronize.

ManagedResource

The ManagedResource kind allows users to define a template to apply for each selected namespace.

apiVersion: automation.kubensync.com/v1alpha1
kind: ManagedResource
metadata:
    name: managedresource-sample
spec:
    avoidResourceUpdate: false
    namespaceSelector:
        regex: "test"
        labelSelector: # (3)!
          matchLabels: {} # (4)!
          matchExpressions: {} # (5)!
    template:
        data: # (1)!
        - name: pull_secret # (2)!
          type: Secret
          ref:
            name: my-pull-secret
            namespace: default
        literal: |
            ---
            apiVersion: v1
            kind: Secret
            metadata:
                name: my-pull-secret
                namespace: {{ .Namespace.Name }}
            type: kubernetes.io/dockerconfigjson
            data:
                .dockerconfigjson: '{{ index .Data.pull_secret ".dockerconfigjson" | base64Encode }}'

1. Tip

   You can read as many secrets or configmaps as you need, even if they are duplicates. Just keep in mind that name should be unique.

2. Info

   This will be the value used on the template

3. Info

   Select namespaces based on labels.

4. Info

   DESCRIPTION:
     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.
   

5. Info

   DESCRIPTION:
     matchExpressions is a list of label selector requirements. The requirements
     are ANDed.
   
     A label selector requirement is a selector that contains values, a key, and
     an operator that relates the key and values.
   
   FIELDS:
     key  <string> -required-
       key is the label key that the selector applies to.
   
     operator     <string> -required-
       operator represents a key's relationship to a set of values. Valid
       operators are In, NotIn, Exists and DoesNotExist.
   
     values       <[]string>
       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.
   

Question

• avoidResourceUpdate: Optional field that changes the default behavior of reconciling existing resources with the desired state. If set to true only non-existing resources will be created an never updated. Default values is false. Existing resources are then left untouched: they are not adopted, so they are not deleted with the ManagedResource.
• namespaceSelector: Specifies the namespaces where you want to apply the template. You can use a regular expression (regex) to match multiple namespaces or filter them by its labels. Regex and labels are ANDed, the namespaces must match both of them to be selected. If none of them are defined, all namespaces will be selected.
• template: Contains the YAML template that you want to apply to the selected namespaces. You can use Go template syntax to customize the resource based on the namespace.
• template.data: Optional field that read Kubernetes resources and expose their contents to be used in the template under .Data.<name>. Set watch: true on an entry to reconcile the ManagedResource whenever that resource changes, see watching data.

Note

Resources a ManagedResource creates, and existing resources it updates, get it as their owner, so deleting the ManagedResource deletes them too. Recreating it creates them again from the template, so manual changes made to them are lost. With avoidResourceUpdate: true a recreated ManagedResource does not take over existing resources, so they are deleted with the old one and only created again on the next reconcile.

Note

When a namespace stops matching the namespaceSelector, because a label is removed or the namespace is deleted, the resources rendered for it are deleted right away, including cluster-scoped resources and resources in other namespaces.

Warning

A resource that every namespace renders the same way, such as a ClusterRole with a fixed name, is tracked under only one of those namespaces. When that namespace stops matching or is deleted, the resource is deleted as well, and it is only created again on the next reconcile of the ManagedResource or of another matching namespace. Until then, anything that references it, such as the RoleBindings of the other namespaces, stops working. Create such shared resources manually, or with a dedicated ManagedResource whose namespaceSelector matches a single namespace.

When a ManagedResource is reconciled

A ManagedResource renders its template into every matching namespace, and removes the resources it no longer renders:

• when it is created, or its spec, labels or annotations change;
• when a resource referenced in template.data with watch: true changes, see watching data;
• when the operator starts, and periodically, about every 10 hours.

A namespace event (a namespace is created, relabelled or deleted) renders the template only into that namespace, or removes the resources rendered for it when it no longer matches.

Changes to the status of the ManagedResource, to the resources it renders, and to data resources that are not watched do not trigger a reconcile. To force one, change an annotation:

kubectl annotate managedresource managedresource-sample kubensync.com/reconcile="$(date +%s)" --overwrite

Status

After reconciliation, the operator updates the status of the ManagedResource with the list of resources it has created and a Ready condition that reflects the outcome.

kubectl get mr

NAME                    READY   AGE
managedresource-sample  True    5m

The Ready condition has the following possible values:

Status	Reason	Meaning
True	Synced	All resources were successfully created or updated across all matching namespaces.
False	ReconcileError	An error occurred during reconciliation. The message field names the failing namespaces and their errors.

Note

Deleting a resource is best effort. If a delete fails, the error is logged, the resource stays listed in status.createdResources, and the delete is retried on the next reconcile; the Ready condition does not change. A resource that no longer exists, or whose kind is no longer served, counts as deleted.

You can inspect the full condition with:

kubectl get mr managedresource-sample -o jsonpath='{.status.conditions[?(@.type=="Ready")]}'

Examples

Check out some real-world use cases of kubensync in the examples section.