Upgrade SOP (Standard Operating Procedure)

This document describes how to upgrade KubeOpenCode on an existing cluster.

Prerequisites

• helm CLI installed
• kubectl or oc CLI with cluster admin access
• Access to the target cluster (kubeopencode-system namespace)

Upgrade Steps

Step 1: Check Current Version

helm list -n kubeopencode-system

Step 2: Review Release Notes

Before upgrading, review the release notes for the target version:

gh release view NEW_VERSION

IMPORTANT: Pay attention to the Breaking Changes section. If CRD changes are listed, you must manually apply CRDs after the Helm upgrade (see Step 4).

Step 3: Upgrade via Helm

helm upgrade kubeopencode oci://ghcr.io/kubeopencode/helm-charts/kubeopencode \
  --version NEW_VERSION_BARE \
  --namespace kubeopencode-system

Step 4: Apply CRD Updates (REQUIRED)

CRITICAL: Helm does not automatically upgrade CRDs during helm upgrade. This is a known Helm limitation. You must always manually apply CRDs after every upgrade, even if you are unsure whether CRD changes are included. Skipping this step will cause strict decoding error: unknown field when applying resources that use new fields.

FOR AI ASSISTANTS: This step is mandatory, not optional. Always apply CRDs and verify new fields after helm upgrade.

Option A: Apply from the Helm chart (if you have the repo checked out at the release tag):

git checkout NEW_VERSION
kubectl apply -f charts/kubeopencode/crds/

Option B: Apply from the OCI chart (pull and extract):

helm pull oci://ghcr.io/kubeopencode/helm-charts/kubeopencode \
  --version NEW_VERSION_BARE --untar
kubectl apply -f kubeopencode/crds/
rm -rf kubeopencode/

Verify CRDs are updated:

kubectl get crd tasks.kubeopencode.io -o jsonpath='{.metadata.resourceVersion}'
kubectl get crd agents.kubeopencode.io -o jsonpath='{.metadata.resourceVersion}'

Step 5: Verify Rollout

# Check deployments are running
kubectl rollout status deployment/kubeopencode-controller -n kubeopencode-system
kubectl rollout status deployment/kubeopencode-server -n kubeopencode-system

# Verify pods are healthy
kubectl get pods -n kubeopencode-system

# Confirm version
helm list -n kubeopencode-system

Step 6: Validate

Run a quick smoke test to ensure the upgrade was successful:

# List agents
kubectl get agents -A

# List tasks
kubectl get tasks -A

# Check controller logs for errors
kubectl logs -n kubeopencode-system deployment/kubeopencode-controller --tail=50

Rollback

If something goes wrong, rollback to the previous version:

helm rollback kubeopencode -n kubeopencode-system

Note: Helm rollback does not rollback CRD changes. If you need to rollback CRDs, manually apply the CRDs from the previous version.

Version History with CRD Changes

This section tracks which releases include CRD changes, so operators know when manual CRD updates are required.

Version	CRD Changes	Description
v0.0.28	Yes	Added status.session fields (sessionID, url) to Task CRD for OpenCode session integration
v0.0.27	Yes	Added extraVolumes and extraVolumeMounts fields to AgentPodSpec in Agent/AgentTemplate CRDs
v0.0.26	Yes	Removed readOnly field from ShareConfig in Agent CRD
v0.0.25	Yes	Added plugins field to Agent/AgentTemplate CRDs; changed config field type from *string to *runtime.RawExtension
v0.0.24	Yes	Added share fields (enabled, expiresAt, allowedIPs) to Agent CRD for token-based terminal sharing
v0.0.18	Yes	Added git.sync (HotReload/Rollout), skills, standby fields to Agent/AgentTemplate CRDs
v0.0.15	Yes	Added AgentTemplate CRD. Unified Agent model (always running + idle timeout). Go upgraded from 1.25 to 1.26. UI improvements: favicon, agent create form, polling for agent status, config page. CLI: added task/agenttemplate/suspend/resume commands.
v0.0.14	Yes	Removed serverConfig from Agent spec; port, persistence, and suspend are now top-level fields. Agent always creates Deployment + Service (no Pod mode). Task now supports templateRef as alternative to agentRef for ephemeral tasks via AgentTemplate.
v0.0.13	Yes	Replaced ServerStatus.readyReplicas (int32) with ready (bool) in Agent CRD
v0.0.9	No (RBAC)	Added agents/finalizers permission to controller ClusterRole (required for Server-mode Agents on OpenShift); fixed UI version display
v0.0.4	Yes	Removed AgentReference.Namespace, TaskExecutionStatus.PodNamespace, AgentSpec.AllowedNamespaces
v0.0.3	No	Bug fixes only
v0.0.2	No	Bug fixes only
v0.0.1	Yes	Initial release