sync

Documentation

Overview

Package implements Kubernetes resources synchronization and provides the following main features:

• basic syncing
• resource pruning
• resource hooks
• sync waves
• sync options

Basic Syncing

Executes equivalent of `kubectl apply` for each specified resource. The apply operations are executed in the predefined order depending of resource type: namespaces, custom resource definitions first and workload resources last.

Resource Pruning

An ability to delete resources that no longer should exist in the cluster. By default obsolete resources are not deleted and only reported in the sync operation result.

Resource Hooks

Hooks provide an ability to create resources such as Pod, Job or any other resource, that are 'executed' before, after or even during the synchronization process. Hooks enable use-cases such as database migration and post sync notifications.

Hooks are regular Kubernetes resources that have `argocd.argoproj.io/hook` annotation:

apiVersion: batch/v1
kind: Job
metadata:
  generateName: schema-migrate-
  annotations:
    argocd.argoproj.io/hook: PreSync

The annotation value indicates the sync operation phase:

• PreSync - executes prior to the apply of the manifests.
• PostSync - executes after all Sync hooks completed and were successful, a successful apply, and all resources in a Healthy state.
• SyncFail - executes when the sync operation fails.
• Sync - executes after all PreSync hooks completed and were successful, at the same time as the apply of the manifests.

Named hooks (i.e. ones with /metadata/name) will only be created once. If you want a hook to be re-created each time either use BeforeHookCreation policy (see below) or /metadata/generateName.

The same resource hook might be executed in several sync phases:

apiVersion: batch/v1
kind: Job
metadata:
  generateName: schema-migrate-
  annotations:
    argocd.argoproj.io/hook: PreSync,PostSync

Hooks can be deleted in an automatic fashion using the annotation: argocd.argoproj.io/hook-delete-policy.

apiVersion: batch/v1
kind: Job
metadata:
  generateName: integration-test-
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded

The following policies define when the hook will be deleted.

• HookSucceeded - the hook resource is deleted after the hook succeeded (e.g. Job/Workflow completed successfully).
• HookFailed - the hook resource is deleted after the hook failed.
• BeforeHookCreation - any existing hook resource is deleted before the new one is created

Sync Waves

The waves allow to group sync execution of syncing process into batches when each batch is executed sequentially one after another. Hooks and resources are assigned to wave zero by default. The wave can be negative, so you can create a wave that runs before all other resources. The `argocd.argoproj.io/sync-wave` annotation assign resource to a wave:

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "5"

Sync Options

The sync options allows customizing the synchronization of selected resources. The options are specified using the annotation 'argocd.argoproj.io/sync-options'. Following sync options are supported:

- SkipDryRunOnMissingResource=true - disables dry run in resource is missing in the cluster - Prune=false - disables resource pruning - Validate=false - disables resource validation (equivalent to 'kubectl apply --validate=false')

How Does It Work Together?

Syncing process orders the resources in the following precedence:

- The phase - The wave they are in (lower values first) - By kind (e.g. namespaces first) - By name

It then determines which the number of the next wave to apply. This is the first number where any resource is out-of-sync or unhealthy. It applies resources in that wave. It repeats this process until all phases and waves are in in-sync and healthy.

Example

Find real-life example in https://github.com/namix-io/sync-engine/blob/master/pkg/engine/engine.go

Index

• type ReconciliationResult
  • func Reconcile(targetObjs []*unstructured.Unstructured, ...) ReconciliationResult
• type SyncContext
  • func NewSyncContext(reconciliationResult ReconciliationResult, restConfig *rest.Config, ...) (SyncContext, func(), error)
• type SyncOpt
  • func WithHealthOverride(override health.HealthOverride) SyncOpt
  • func WithInitialState(phase common.OperationPhase, message string, ...) SyncOpt
  • func WithLogr(log logr.Logger) SyncOpt
  • func WithManifestValidation(enabled bool) SyncOpt
  • func WithNamespaceCreation(createNamespace bool, namespaceModifier func(*unstructured.Unstructured) bool) SyncOpt
  • func WithOperationSettings(dryRun bool, prune bool, force bool, skipHooks bool) SyncOpt
  • func WithPermissionValidator(validator common.PermissionValidator) SyncOpt
  • func WithPrune(prune bool) SyncOpt
  • func WithPruneLast(enabled bool) SyncOpt
  • func WithPrunePropagationPolicy(policy *metav1.DeletionPropagation) SyncOpt
  • func WithReplace(replace bool) SyncOpt
  • func WithResourceModificationChecker(enabled bool, diffResults *diff.DiffResultList) SyncOpt
  • func WithResourcesFilter(...) SyncOpt
  • func WithSkipHooks(skipHooks bool) SyncOpt
  • func WithSyncWaveHook(syncWaveHook common.SyncWaveHook) SyncOpt

Types

type ReconciliationResult

type ReconciliationResult struct {
	Live   []*unstructured.Unstructured
	Target []*unstructured.Unstructured
	Hooks  []*unstructured.Unstructured
}

func Reconcile

func Reconcile(targetObjs []*unstructured.Unstructured, liveObjByKey map[kube.ResourceKey]*unstructured.Unstructured, resInfo kubeutil.ResourceInfoProvider) ReconciliationResult

type SyncContext

type SyncContext interface {
	// Terminate terminates sync operation. The method is asynchronous: it starts deletion is related K8S resources
	// such as in-flight resource hooks, updates operation status, and exists without waiting for resource completion.
	Terminate(ctx context.Context)
	// Executes next synchronization step and updates operation status.
	Sync(ctx context.Context)
	// Returns current sync operation state and information about resources synchronized so far.
	GetState(ignoreUnchanged bool) (common.OperationPhase, string, []common.ResourceSyncResult)
}

SyncContext defines an interface that allows to execute sync operation step or terminate it.

func NewSyncContext

func NewSyncContext(
	reconciliationResult ReconciliationResult,
	restConfig *rest.Config,
	rawConfig *rest.Config,
	kubectl kubeutil.Kubectl,
	openAPISchema openapi.Resources,
	opts ...SyncOpt,
) (SyncContext, func(), error)

NewSyncContext creates new instance of a SyncContext

type SyncOpt

type SyncOpt func(ctx *syncContext)

SyncOpt is a callback that update sync operation settings

func WithHealthOverride

func WithHealthOverride(override health.HealthOverride) SyncOpt

WithHealthOverride sets specified health override

func WithInitialState

func WithInitialState(phase common.OperationPhase, message string, results []common.ResourceSyncResult, startedAt metav1.Time) SyncOpt

WithInitialState sets sync operation initial state

func WithLogr

func WithLogr(log logr.Logger) SyncOpt

WithLogr sets the logger to use.

func WithManifestValidation

func WithManifestValidation(enabled bool) SyncOpt

WithManifestValidation enables or disables manifest validation

func WithNamespaceCreation

func WithNamespaceCreation(createNamespace bool, namespaceModifier func(*unstructured.Unstructured) bool) SyncOpt

WithNamespaceCreation will create non-exist namespace

func WithOperationSettings

func WithOperationSettings(dryRun bool, prune bool, force bool, skipHooks bool) SyncOpt

WithOperationSettings allows to set sync operation settings

func WithPermissionValidator

func WithPermissionValidator(validator common.PermissionValidator) SyncOpt

WithPermissionValidator sets specified permission validator

func WithPrune

func WithPrune(prune bool) SyncOpt

WithPrune specifies if resource pruning enabled

func WithPruneLast

func WithPruneLast(enabled bool) SyncOpt

WithPruneLast enables or disables pruneLast

func WithPrunePropagationPolicy

func WithPrunePropagationPolicy(policy *metav1.DeletionPropagation) SyncOpt

WithPrunePropagationPolicy sets specified permission validator

func WithReplace

func WithReplace(replace bool) SyncOpt

func WithResourceModificationChecker

func WithResourceModificationChecker(enabled bool, diffResults *diff.DiffResultList) SyncOpt

WithResourceModificationChecker sets resource modification result

func WithResourcesFilter

func WithResourcesFilter(resourcesFilter func(key kube.ResourceKey, target *unstructured.Unstructured, live *unstructured.Unstructured) bool) SyncOpt

WithResourcesFilter sets sync operation resources filter

func WithSkipHooks

func WithSkipHooks(skipHooks bool) SyncOpt

WithSkipHooks specifies if hooks should be enabled or not

func WithSyncWaveHook

func WithSyncWaveHook(syncWaveHook common.SyncWaveHook) SyncOpt

WithSyncWaveHook sets a callback that is invoked after application of every wave