Upgrade Guide

RELEASE_REGISTRY="us-docker.pkg.dev/velt-sdk/velt-releases"

# Enumerate releases (newest first) and pick the target with the operator —
# default to the newest, but the operator may pin an intermediate version.
oras pull -o . "$RELEASE_REGISTRY/velt-selfhost-index:latest"      # writes index.json
python3 -c "import json;[print(r['selfHostVersion'], r['releasedAt']) for r in json.load(open('index.json'))['releases']]"

TARGET_VERSION="<chosen X.Y.Z>"
oras pull -o . "$RELEASE_REGISTRY/velt-selfhost-manifest:$TARGET_VERSION"   # writes manifest.json

# MANDATORY: verify the manifest signature (same rule as install Phase 0.1).
# Only deploy releases that verify successfully.
MANIFEST_DIGEST=$(oras manifest fetch --descriptor "$RELEASE_REGISTRY/velt-selfhost-manifest:$TARGET_VERSION" | python3 -c "import json,sys;print(json.load(sys.stdin)['digest'])")
cosign verify \
  --certificate-identity-regexp 'https://github\.com/[^/]+/shared-firebase-function/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  "$RELEASE_REGISTRY/velt-selfhost-manifest@$MANIFEST_DIGEST"

python3 - <<'EOF'
import json
new = json.load(open('manifest.json'))
old = json.load(open('velt-selfhost-state.json'))['release']
def row(name, o, n): print(f"{name:10} {'CHANGED' if o != n else 'same':8} {o} -> {n}" if o != n else f"{name:10} same     {o}")
row('backend',  old['backend']['digest'],        new['backend']['digest'])
row('module',   old['backend']['moduleSha256'],  new['backend']['moduleSha256'])
row('console',  old['console']['version'],       new['console']['version'])
row('sdk',      old['sdk']['testedVersion'],     new['sdk']['testedVersion'])
EOF

DEPLOYED_SDK="<from state file artifacts.sdkCdnPath, e.g. 6.0.0-beta.11>"
MIN_SDK=$(python3 -c "import json;print(json.load(open('manifest.json'))['sdk']['minVersion'])")
# sort -V: the min version must sort first (or equal) for the fence to pass
[ "$(printf '%s\n%s\n' "$MIN_SDK" "$DEPLOYED_SDK" | sort -V | head -1)" = "$MIN_SDK" ] \
  && echo "SDK FENCE: PASS" || echo "SDK FENCE: FAIL — U3 is MANDATORY in this upgrade"

python3 -c "import json;print('console configSchemaVersion:', json.load(open('manifest.json'))['console']['configSchemaVersion'])"
# Compare against the installed console's configSchemaVersion (state file release.console).
# Different → U2 is MANDATORY and must complete before or immediately after U1's apply.

NEW_DIGEST=$(python3 -c "import json;print(json.load(open('manifest.json'))['backend']['digest'])")
SRC=$(python3 -c "import json;print(json.load(open('manifest.json'))['backend']['imageByDigest'])")
DEST="us-docker.pkg.dev/$PROJECT_ID/velt/velt-functions"   # the SAME dest repo the install used

crane copy "$SRC" "$DEST:${TARGET_VERSION}"                 # (docker pull/tag/push fallback: install 1.4 — remember --platform linux/amd64 on arm hosts)
crane digest "$DEST:${TARGET_VERSION}"                       # MUST equal $NEW_DIGEST
cosign verify \
  --certificate-identity-regexp 'https://github\.com/[^/]+/shared-firebase-function/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  "$DEST@$NEW_DIGEST"                                        # MUST print Verified OK — STOP otherwise
NEW_IMAGE_REF="$DEST@$NEW_DIGEST"                            # pin BY DIGEST, as always

MODULE_REF=$(python3 -c "import json;print(json.load(open('manifest.json'))['backend']['moduleRef'])")
MODULE_SHA=$(python3 -c "import json;print(json.load(open('manifest.json'))['backend']['moduleSha256'])")
oras pull -o . "$MODULE_REF"
MODULE_TAR=$(ls velt-backend-module-${TARGET_VERSION}.tar.gz)
echo "$MODULE_SHA  $MODULE_TAR" | shasum -a 256 -c -         # MUST print OK

OLD_MODULE_DIR="<artifacts.moduleDir from the state file>"
export MODULE_DIR="$(pwd)/velt-backend-module-${TARGET_VERSION}"
mkdir -p "$MODULE_DIR" && tar -xzf "$MODULE_TAR" -C "$MODULE_DIR"

# The Terraform STATE and tfvars are the deployment's memory — carry them over.
# (If the operator configured a remote state backend at install time, skip the
# state copy; init below will find it. The tfvars copy is always needed.)
cp "$OLD_MODULE_DIR/terraform/velt.auto.tfvars" "$MODULE_DIR/terraform/"
cp "$OLD_MODULE_DIR/terraform/terraform.tfstate"* "$MODULE_DIR/terraform/" 2>/dev/null || true

cd "$MODULE_DIR/terraform"
# Point the image pin at the new digest:
#   velt_image = "<NEW_IMAGE_REF>"
# Leave every other tfvars value alone unless the new module README says otherwise.
terraform init && terraform validate

terraform plan -out=upgrade.plan

# New module versions may ADD entries to secrets_to_seed. Cloud Run refuses a
# revision mounting a secret with no enabled version — seed NEW ids before the apply.
terraform apply -target=google_secret_manager_secret.required \
                -target=google_secret_manager_secret_iam_member.runtime_accessor \
                -target=google_secret_manager_secret_version.optional_placeholder
terraform output -json secrets_to_seed
# Diff against what exists: any id in the output with no enabled version needs seeding.
for id in $(terraform output -json secrets_to_seed | python3 -c "import json,sys;print(' '.join(json.load(sys.stdin)))"); do
  gcloud secrets versions list "$id" --project="$PROJECT_ID" --filter="state=enabled" --limit=1 --format="value(name)" | grep -q . \
    || echo "NEEDS SEEDING: $id"
done
# Seed per the install guide 2.4 value rules (real keys for enabled AI modules,
# "placeholder-not-configured" for listed-but-unused, fresh random for crypto keys —
# NEVER regenerate an EXISTING crypto secret: JWT_SECRET_KEY / PLUGIN_CRYPTO_* rotate
# only via a deliberate, separately-planned rotation, not as an upgrade side effect).

terraform apply upgrade.plan          # rolling Cloud Run revisions — near-zero downtime
terraform plan                        # MUST end "No changes." (retryables: install guide list)
terraform output -json service_urls > service-urls.json

BUNDLE_REF=$(python3 -c "import json;print(json.load(open('manifest.json'))['console']['bundleRef'])")
CONSOLE_SHA=$(python3 -c "import json;print(json.load(open('manifest.json'))['console']['sha256'])")
oras pull -o . "$BUNDLE_REF"
echo "$CONSOLE_SHA  $(ls console-dist-*.tar.gz)" | shasum -a 256 -c -    # MUST print OK

SDK_REF=$(python3 -c "import json;print(json.load(open('manifest.json'))['sdk']['bundleRef'])")
SDK_SHA=$(python3 -c "import json;print(json.load(open('manifest.json'))['sdk']['sha256'])")
SDK_VERSION=$(python3 -c "import json;print(json.load(open('manifest.json'))['sdk']['testedVersion'])")
oras pull -o . "$SDK_REF"
echo "$SDK_SHA  $(ls veltdev-sdk-*.tgz)" | shasum -a 256 -c -            # MUST print OK

# State file: replace `release` with the new manifest, keep the old one on disk
mv manifest.json "manifest-${TARGET_VERSION}.json"
# update velt-selfhost-state.json: release = new manifest, log += upgrade record