Skip to content
🛥️🐳 KSail

GitOps Workflows

Enable GitOps with Flux or ArgoCD for declarative, Git-driven deployments. KSail automatically installs the GitOps engine, scaffolds FluxInstance or ArgoCD Application CRs, and provides commands to package manifests as OCI artifacts, push to the local registry, and trigger reconciliation.

Terminal window
ksail cluster init --gitops-engine Flux --local-registry localhost:5050
ksail cluster create
ksail workload push
ksail workload reconcile

OCI Artifact Tag

Section titled “OCI Artifact Tag”

spec.workload.tag sets the OCI artifact tag used by both workload push and GitOps reconciliation (Flux OCIRepository / ArgoCD Application). Configure it in ksail.yaml:

spec:
  workload:
    tag: v1.2.3  # default: dev

The tag is resolved differently depending on the context:

  • Push (ksail workload push): CLI oci:// ref > spec.workload.tag > registry-embedded tag > dev.
  • Reconciliation (Flux / ArgoCD): spec.workload.tag > registry-embedded tag > dev.

See Declarative Configuration for the full spec.workload reference.

Tag drift auto-repair

Section titled “Tag drift auto-repair”

ksail cluster update detects when the live GitOps sync ref (Flux OCIRepository tag or ArgoCD targetRevision) has drifted from the configured spec.workload.tag and reconciles it in-place — no manual intervention required. This keeps the cluster’s GitOps engine aligned with your declared configuration automatically.

Commands

Section titled “Commands”
CommandDescription
ksail workload pushPackage and push manifests to registry
ksail workload reconcileTrigger GitOps sync and wait for completion

Automatic HelmRelease Recovery

Section titled “Automatic HelmRelease Recovery”

Before polling Kustomizations, ksail workload reconcile automatically detects and resets HelmReleases stuck in a non-recoverable state (Ready=False with a failure reason such as InstallFailed/UpgradeFailed, or Stalled=True). Each stuck release is suspended then resumed so the helm-controller can retry, eliminating the need for manual kubectl patch suspend/resume workarounds.

HelmReleases with DependencyNotReady are skipped — these are transient and resolve on their own. Individual reset failures are logged but do not abort reconciliation.

Automatic Failure Diagnostics

Section titled “Automatic Failure Diagnostics”

When ksail workload reconcile fails, KSail automatically collects and displays a targeted diagnostic report — no manual kubectl investigation required.

The report includes:

  • Failing GitOps resources — Flux Kustomizations, HelmReleases, and OCIRepositories (or ArgoCD Applications) with their condition reason and message (only non-ready resources are shown)
  • Failing pods — non-ready pods in the GitOps namespace
  • Recent warning events — all Kubernetes warning events from the GitOps namespace in the last 5 minutes

Diagnostics are best-effort with a 15-second timeout. If the cluster is unreachable, the section is silently skipped so the original reconciliation error remains prominent.

Excluding Flux Kustomizations from Progress Monitoring

Section titled “Excluding Flux Kustomizations from Progress Monitoring”

This feature is Flux-specific and does not affect ArgoCD Application reconciliation.

Some Flux Kustomizations may be intentionally long-running or should not block command completion. You can exclude specific Kustomizations from progress monitoring using either an annotation or a CLI flag.

Annotation — add to the Kustomization manifest:

metadata:
  annotations:
    ksail.devantler.tech/reconcile-exclude: "true"

CLI flag — pass one or more names at the command line (repeatable, comma-separated):

Terminal window
ksail workload reconcile --exclude my-kustomization
ksail workload reconcile --exclude "kust-a, kust-b"

Excluded Kustomizations are skipped during the progress tracking phase. They are still applied to the cluster; they simply do not block ksail workload reconcile from completing.

Automatic Retry

Section titled “Automatic Retry”

Both workload push and workload reconcile automatically retry on transient failures:

  • Up to 3 attempts with exponential backoff starting at 5s (capped at 30s); with the current 3-attempt limit, retries wait 5s after the first failure and 10s after the second
  • Retryable conditions are determined by the shared netretry.IsRetryable predicate, including examples such as HTTP 429 (rate-limit), 5xx server errors, connection refused, i/o timeout, unexpected EOF, no such host, redirect limit, TCP resets, and context deadline exceeded
  • A warning is printed on each retry attempt so you can follow progress

For ksail workload reconcile, the --timeout flag (if set) is a per-attempt bound — total runtime can reach up to maxAttempts × timeout plus backoff.

Section titled “Related”