Automated Updates (GitOps)¶

KubeManta does not update itself. There is no in-product self-updater and no CronJob in the chart: an SRE tool that rewrites its own deployment would need permission to modify itself, and it could not work in an air-gapped cluster.

If you want updates applied automatically, the supported path is GitOps — Flux or Argo CD pulling the chart from the stable channel, with your own health gate and rollback. The decision of when an update lands, and the guardrails around it, stay in your repository and your review process.

If you do not run GitOps, upgrade with helm upgrade as described in Install. If you turn on the update check in Admin (it is off by default), KubeManta shows when a newer release is available and the exact command for your install.

Before you start¶

Track the stable channel, with a version range. The chart lives at oci://registry.kubemanta.com/kubemanta/charts/stable/kubemanta. Pin a semver range such as >=1.3.0 <2.0.0 so you take minor and patch releases automatically and a major version needs a deliberate change. A plain range like this never selects a pre-release (-rc.N) tag; do not add one to the range in production.
Values live in Git, in full. A GitOps controller supplies the complete values on every sync. There is no equivalent of --reset-then-reuse-values: anything you set once with helm upgrade --set and did not copy into your GitOps values is dropped on the first sync. Before handing an existing install to a controller, capture what you set:
```
helm get values kubemanta -n kubemanta-system -o yaml > kubemanta-values.yaml
```
Move the licence key and any password out of that file into a Secret (see below) before committing it.

Settings you change in the product (alert rules, integrations, namespace scope, users) are stored in KubeManta's database on its volume, not in the chart values, so a sync never resets them. - One replica, by design. The agent owns a ReadWriteOnce volume and an embedded database, so the chart refuses replicaCount > 1 and uses the Recreate strategy. Expect a short gap while the old agent pod stops and the new one starts; the database migrates on start. - Let the chart's preflight run. It runs as a pre-upgrade hook (Flux) or a PreSync hook (Argo CD) and refuses an upgrade that would fail, before anything changes.

Registry credentials¶

The chart and images are pulled from registry.kubemanta.com with your licence key as the password and license as the username. The images are pulled with the license.key you set in the chart values. The chart itself is pulled by your controller: for Flux, store the credential as a Secret in the namespace the OCIRepository lives in (for Argo CD, see Registry access below):

kubectl create secret docker-registry kubemanta-registry \
  --docker-server=registry.kubemanta.com \
  --docker-username=license \
  --docker-password='<LICENSE-KEY>' \
  -n kubemanta-system

Flux¶

Flux's helm-controller runs real Helm installs and upgrades against the cluster, so the chart behaves exactly as it does under helm upgrade.

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: kubemanta
  namespace: kubemanta-system
spec:
  interval: 1h
  url: oci://registry.kubemanta.com/kubemanta/charts/stable/kubemanta
  ref:
    semver: ">=1.3.0 <2.0.0"
  secretRef:
    name: kubemanta-registry
  layerSelector:
    mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip
    operation: copy
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: kubemanta
  namespace: kubemanta-system
spec:
  interval: 30m
  chartRef:
    kind: OCIRepository
    name: kubemanta
  # Upgrades include a database migration and a Recreate rollout; allow time.
  timeout: 15m
  install:
    remediation:
      retries: 2
  upgrade:
    cleanupOnFail: true
    remediation:
      # One attempt, then roll back. Do not retry: see "Health gate" below.
      retries: 0
      remediateLastFailure: true
      strategy: rollback
  values:
    global:
      hostname: km.example.com
  valuesFrom:
    # license.key (and security.adminPassword, if you set one) come from a
    # Secret rather than Git.
    - kind: Secret
      name: kubemanta-values
      valuesKey: values.yaml

The kubemanta-values Secret holds the sensitive part of your values:

cat > secret-values.yaml <<'EOF'
license:
  key: <LICENSE-KEY>
EOF
kubectl create secret generic kubemanta-values \
  --from-file=values.yaml=secret-values.yaml -n kubemanta-system
rm secret-values.yaml

Health gate and rollback. Helm waits for the Deployments to become Ready within timeout; if they do not, the upgrade is marked failed and Flux rolls back to the previous revision (strategy: rollback). A rollback restores the previous images and manifests; the database keeps any migration the newer version applied, which older versions are built to tolerate.

Keep upgrade.remediation.retries at 0. Because the agent uses the Recreate strategy, every upgrade attempt stops the running agent first, so each retry is another outage of up to timeout followed by a rollback. With retries: 2 and timeout: 15m, one bad release keeps KubeManta down for most of an hour before Flux gives up. With retries: 0 and remediateLastFailure: true, Flux makes one attempt, rolls back, and stops until you change something in Git.

Argo CD¶

Argo CD renders the chart with helm template and applies the result itself. Two consequences need configuration.

Keep the generated Secrets stable. On a first install the chart generates three Secrets — the encryption key for stored credentials (<release>-enc), the initial admin password (<release>-admin), and the Expert Mode shared secret (<release>-expert-exec) — and on every later helm upgrade it reads them back so they never change. helm template cannot read from the cluster, so under Argo CD each render produces new random values. Left alone, a sync would replace the encryption key and every credential KubeManta has stored (AI provider keys, SSO and integration secrets) would become unreadable.

Choose one of two ways to keep them stable.

Option 1 — supply the values yourself (from your secret manager, never in plain Git). Every render is then identical. This needs chart 1.3.0 or later: 1.2.x charts ignore expertMode.execSecret, so on 1.2.x use Option 2 for the -expert-exec Secret.

security:
  encryptionKey: <openssl rand -base64 32>   # losing it = losing stored credentials
  adminPassword: <initial admin password>
expertMode:
  execSecret: <40+ random characters>         # only if expertMode.enabled

The terminal needs no entry here. Its credentials are generated by the agent in memory each time it starts, and nothing about them is rendered by the chart, so every render is the same without them.

Upgrading from 1.3.1 or earlier

Up to 1.3.1 this list included terminal.proxySecret, and the chart kept a fourth Secret, <release>-terminal. The chart no longer reads terminal.proxySecret (nor terminal.signingKey / terminal.signingPubkey) and no longer renders that Secret. Remove the values from your Application or values file, drop the kubemanta-terminal entry from ignoreDifferences, and delete the Secret if it is still there, since nothing uses it any more: kubectl -n kubemanta-system delete secret kubemanta-terminal. Upgrade the chart and the agent image together; if you pin image.tag or image.digest, move it in the same sync.

Option 2 — let the chart generate them once and tell Argo CD never to overwrite their contents: ignoreDifferences together with the RespectIgnoreDifferences sync option, as in the Application below. Both are required — ignoreDifferences alone only hides the diff, and the next sync still writes the new values.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kubemanta
  namespace: argocd
spec:
  project: default
  source:
    repoURL: registry.kubemanta.com/kubemanta/charts/stable
    chart: kubemanta
    targetRevision: ">=1.3.0 <2.0.0"
    helm:
      releaseName: kubemanta
      valuesObject:
        global:
          hostname: km.example.com
  destination:
    server: https://kubernetes.default.svc
    namespace: kubemanta-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - RespectIgnoreDifferences=true
    retry:
      limit: 3
      backoff:
        duration: 30s
        factor: 2
        maxDuration: 5m
  ignoreDifferences:
    - kind: Secret
      name: kubemanta-enc
      jsonPointers: [/data]
    - kind: Secret
      name: kubemanta-admin
      jsonPointers: [/data]
    - kind: Secret
      name: kubemanta-expert-exec
      jsonPointers: [/data]

The Secret names above assume the release is named kubemanta. If your release name contains kubemanta they are <release>-enc and so on; otherwise they are <release>-kubemanta-enc and so on. Check with kubectl get secrets -n kubemanta-system after the first sync.

Registry access. Register the chart registry as an OCI Helm repository with the same credentials:

argocd repo add registry.kubemanta.com/kubemanta/charts/stable \
  --type helm --enable-oci --name kubemanta \
  --username license --password '<LICENSE-KEY>'

Licence key. KubeManta reads its licence key from license.key in the chart values, and Argo CD takes values only from the Application or from files in a Git repository. Keep the key out of a public or widely-shared repository: inject it from your secret store (for example with the Argo CD Vault Plugin or an equivalent config-management plugin), or keep a values file holding only license.key in a private repository that only Argo CD can read, and list it under helm.valueFiles.

Health gate and rollback. The preflight hook fails the sync before anything is applied if the upgrade cannot succeed. A problem the preflight cannot see (an image that will not pull or start, say) shows up as the Application staying Progressing; it turns Degraded only when the Deployment's progress deadline passes (10 minutes by default), and because of the Recreate strategy the agent is down for that whole time. Alert on Progressing, not only Degraded. Argo CD does not roll back on its own: revert the targetRevision (or pin the previous version) in Git, and it syncs back.

Air-gapped clusters¶

Point the controller at your internal mirror of the chart, never at registry.kubemanta.com. Mirror each release with the Air-gapped install tool and commit the kubemanta-airgap-values.yaml it generates to your GitOps repository: it points every image, including the ones KubeManta starts at runtime, at your mirror. For Flux, the registry Secret's --docker-server must be your mirror's hostname. Mirror a release, review it, then move the version your GitOps repository references.

With security.airgap.enabled=true the chart does not render the preflight hook (it needs to reach a public registry), so the upgrade gate is the one described under Health gate and rollback: the Deployment's progress deadline for Argo CD, and the timeout and single rollback for Flux. See Restricted clusters for the images to mirror.

Pairing with release notifications¶

GitOps decides when an update is applied; it does not tell you that one exists. Watch the Changelog — and for a controller that tracks a version range, review each release there before it reaches production.