Skip to content

v0.1.1 Upgrade Notes

Summary

v0.1.1 automatically migrates every enabled self-hosted model-cache PVC to the revision-isolated snapshot-v2 publication contract during reconciliation. It also advances the supported Gateway API/Traefik pin-set. Follow the ordered Gateway API, tag, and immutable-tag kagent compatibility steps below.

Config and values migrations

  • None.

SOPS and secret changes

  • None.

Manual steps

  1. Advance the out-of-band Gateway API bundle from v1.4.0 to v1.5.1. Install the standard channel first, remove the upstream channel-change guard, then install the experimental channel used by the reference profile:
kubectl apply --server-side --force-conflicts \
  -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml
kubectl delete validatingadmissionpolicybinding,validatingadmissionpolicy \
  safe-upgrades.gateway.networking.k8s.io --ignore-not-found
kubectl apply --server-side --force-conflicts \
  -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/experimental-install.yaml

The field-ownership transfer is intentional: these CRDs are the documented out-of-band bundle. Confirm both the version and channel before continuing:

kubectl get crd \
  gateways.gateway.networking.k8s.io \
  tlsroutes.gateway.networking.k8s.io \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version}{"\t"}{.metadata.annotations.gateway\.networking\.k8s\.io/channel}{"\n"}{end}'

Both rows must report v1.5.1 and experimental.

  1. Change the Flux GitRepository tag to v0.1.1. Wait for the top-level flux-system Kustomization to apply the v0.1.1 child definitions; kagent can report the schema error corrected below during this bounded transition.

  2. Apply the v0.1.1 kagent compatibility correction. The immutable tag placed the pod-log approval fields one level above the pinned CRD schema and shipped the preceding admission expression. Suspend the top-level renderer so it cannot overwrite the child patch, suspend the policy renderer, install the reviewed fail-closed policy correction, and add the structural transform to the kagent Flux Kustomization:

flux suspend kustomization flux-system
flux suspend kustomization policies
kubectl patch validatingadmissionpolicy \
  approved-agent-references.fgentic.dev --type json --patch '[
    {
      "op": "replace",
      "path": "/spec/validations/9/expression",
      "value": "!has(object.spec.declarative.tools) || ((object.metadata.name == \"platform-helper\" && size(object.spec.declarative.tools) == 2 && object.spec.declarative.tools.exists(t, has(t.mcpServer) && has(t.mcpServer.toolNames) && t.mcpServer.toolNames == [\"k8s_get_resources\", \"k8s_describe_resource\", \"k8s_get_events\", \"k8s_get_resource_yaml\"]) && object.spec.declarative.tools.exists(t, has(t.mcpServer) && has(t.mcpServer.toolNames) && t.mcpServer.toolNames == [\"k8s_get_pod_logs\"])) || (object.metadata.name == \"knowledge-agent\" && size(object.spec.declarative.tools) == 1))"
    },
    {
      "op": "replace",
      "path": "/spec/validations/9/message",
      "value": "only platform-helper and knowledge-agent may declare their exact governed tool servers"
    },
    {
      "op": "replace",
      "path": "/spec/validations/11/expression",
      "value": "!has(object.spec.declarative.tools) || object.spec.declarative.tools.all(t, (object.metadata.name == \"platform-helper\" && ((t.mcpServer.toolNames == [\"k8s_get_pod_logs\"] && has(t.mcpServer.requireApproval) && t.mcpServer.requireApproval == [\"k8s_get_pod_logs\"] && has(t.mcpServer.allowedHeaders) && t.mcpServer.allowedHeaders == [\"X-Fgentic-Approval\"]) || (t.mcpServer.toolNames != [\"k8s_get_pod_logs\"] && !has(t.mcpServer.requireApproval) && !has(t.mcpServer.allowedHeaders)))) || (object.metadata.name == \"knowledge-agent\" && !has(t.mcpServer.requireApproval) && has(t.mcpServer.allowedHeaders) && t.mcpServer.allowedHeaders == [\"X-Fgentic-Identity\"]))"
    },
    {
      "op": "replace",
      "path": "/spec/validations/11/message",
      "value": "tool approval and propagated headers must match the exact reviewed surface"
    }
  ]'
kubectl -n flux-system patch kustomization kagent --type merge --patch '{
  "spec": {
    "patches": [{
      "target": {
        "group": "kagent.dev",
        "version": "v1alpha2",
        "kind": "Agent",
        "name": "platform-helper",
        "namespace": "kagent"
      },
      "patch": "- op: add\n  path: /spec/declarative/tools/1/mcpServer/requireApproval\n  value: [k8s_get_pod_logs]\n- op: add\n  path: /spec/declarative/tools/1/mcpServer/allowedHeaders\n  value: [X-Fgentic-Approval]\n- op: remove\n  path: /spec/declarative/tools/1/requireApproval\n- op: remove\n  path: /spec/declarative/tools/1/allowedHeaders\n"
    }]
  }
}'

Keep flux-system and policies suspended while v0.1.1 is pinned. Their child Kustomizations and the corrected admission objects remain active. The next release contains the correction declaratively and removes this one-release compatibility step.

  1. Reconcile the active child dependency graph. After reconciliation:

  2. Require every non-suspended Flux Kustomization and HelmRelease to be Ready.

  3. Confirm the PostgreSQL PVC identity is unchanged.
  4. Wait for each enabled one-shot model loader Job to succeed and its serving Pod to become Ready before judging model availability. Do not delete the retained cache PVC or rewrite its .ready marker.

Rollback

  • Pin the previous release tag in the Flux GitRepository, resume flux-system, and let it restore the previous child definitions. Resume policies after the previous tag has applied; the top-level reconciliation removes the temporary kagent.spec.patches entry. The Gateway API v1.5.1 CRDs are backward-compatible with the v0.1.0 resources and do not need to be downgraded. A pre-snapshot-v2 loader does not recognize the new readiness marker and can re-download the configured revision before its serving Pod becomes Ready; keep the loader's existing prompt-free public HTTPS path available and let that Job finish.

BOM delta

  • v0.1.1 introduces the generated, fail-closed release/bom.yaml for the reference release profile. It inventories the exact chart sources, Helm releases, image digests, and explicit image tags reconciled by this tag; v0.1.0 had no equivalent machine-readable BOM.