cd/docs/user-guide/sync-kubectl.md

Sync Applications with Kubectl

You can use "kubectl" to ask Hanzo CD to synchronize applications the same way you can use the CLI or UI. Many configurations like "force", "prune", "apply" and even synchronizing a specific list of resources are equally supported. This is done by applying or patching the Hanzo CD application with a document that defines an "operation".

This "operation" defines how a synchronization should be done and for what resources these synchronization is to be done.

There are many configuration options that can be added to the "operation". Next, a few of them are explained. For more details, you can have a look at the CRD applications.apps.hanzo.ai. Some of them are required, whereas others are optional.

To ask Hanzo CD to synchronize all resources of a given application, we can do:

apiVersion: apps.hanzo.ai/v1alpha1
kind: Application
metadata:
  name: <app-name>
  namespace: <namespace>
spec:
  ...
operation:
  initiatedBy:
    username: <username>
  sync:
    syncStrategy:
      hook: {}

$ kubectl apply -f <apply-file>

The most important part is the "sync" definition in the "operation" field. You can pass optional information like "info" or "initiatedBy". "info" allows you to add information about the operation in the form of a list. "initiatedBy" contains information about who initiated the operation request.

Or if you prefer, you also can patch:

operation:
  initiatedBy:
    username: <username>
  sync:
    syncStrategy:
      hook: {}

$ kubectl patch -n <namespace> app <app-name> --patch-file <patch-file> --type merge

Be aware that patches, specially with merge strategies, may not work the way you expect especially if you change sync strategies or options. In these cases, "kubectl apply" gives better results.

Either with a "kubectl patch" or "kubectl apply", the state of the synchronization is reported in the "operationState" field in the application object.

$ kubectl get -n <namespace> app <app-name> -o yaml
...
status:
  operationState:
    finishedAt: "2023-08-03T11:16:17Z"
    message: successfully synced (all tasks run)
    phase: Succeeded

Apply and Hook synchronization strategies

There are two types of synchronization strategies: "hook", which is the default value, and "apply".

An "apply" sync strategy tells Hanzo CD to "kubectl apply", whereas a "hook" sync strategy informs Hanzo CD to submit any resource that's referenced in the operation. This way the synchronization of these resources will take into consideration any hook the resource has been annotated with.

operation:
  sync:
    syncStrategy:
      apply: {}

operation:
  sync:
    syncStrategy:
      hook: {}

Both strategies support "force". However, you need to be aware that a force operation deletes the resource when patch encounters a conflict after having retried 5 times.

operation:
  sync:
    syncStrategy:
      apply:
        force: true

operation:
  sync:
    syncStrategy:
      hook:
        force: true

# Prune

If you want to prune your resources before applying, you can instruct Hanzo CD to do so:

operation:
  sync:
    prune: true

List of resources

There's always the possibility to pass a list of resources. This list can be all resources the application manages or only a subset, for example resources that remained out of sync for some reason.

Only "kind" and "name" are required fields when referencing resources, but the fields "groups" and "namespace" can also be defined:

operation:
  sync:
    resources:
      - kind: Namespace
        name: namespace-name
      - kind: ServiceAccount
        name: service-account-name
        namespace: namespace-name
      - group: networking.k8s.io
        kind: NetworkPolicy
        name: network-policy-name
        namespace: namespace-name

Sync Options

In an operation, you can also pass sync-options. Each of these options is passed as "name=value" pairs. For example:

operations:
  sync:
    syncOptions:
      - Validate=false
      - Prune=false

For more information about sync options, please refer to sync-options