Skip to content

Runtime Bundle Secret Lifecycle (HyOps Module)

  • Purpose: Publish a local bundle file into a Kubernetes Secret through the normal HyOps execution path.
  • Trigger: A private app or generated build output must be delivered to a cluster without encoding that logic into the public workload repository.
  • Impact: Creates or updates one namespaced Kubernetes Secret and publishes the applied bundle SHA-256 into module state.
  • Severity: P2
  • Rollback strategy: Destroy the module state instance to remove the synced secret.

Context

Module ref: platform/k8s/runtime-bundle-secret

This module is cluster-neutral. It uses a resolved kubeconfig and a local file path on the controller to:

  • ensure the target namespace exists when requested
  • create or update an Opaque Secret
  • store the file under bundle_key
  • publish bundle_sha256 for downstream verification
  • optionally restart named rollout targets when the bundle changes

HyOps applies the generated Secret manifest with Kubernetes server-side apply. That keeps larger runtime bundles from failing on kubectl apply annotation limits caused by the client-side last-applied-configuration payload.

Use it for private app payloads such as:

  • SSR runtime bundles
  • generated static-site packages
  • internal app payloads that should not live in the public workloads repo

Preconditions

  • the target kubeconfig is already published or provided explicitly
  • the local bundle file already exists on the controller
  • the target namespace and secret name are agreed

Execute

hyops apply --env dev \
  --module platform/k8s/runtime-bundle-secret \
  --state-instance burst_runtime_proof \
  --inputs /path/to/inputs.yml

Minimal input shape:

kubeconfig_state_ref: "platform/gcp/gke-kubeconfig#gke_burst_kubeconfig"
namespace: "academy"
secret_name: "academy-website-runtime"
bundle_source_path: "/path/to/runtime-bundle.tgz"
bundle_key: "dist.tgz"
restart_targets:
  - "deployment/showcase-burst-web"
rollout_timeout_s: 300

Verification

Check module outputs:

jq '.status, .outputs' \
  "$HOME/.hybridops/envs/dev/state/modules/platform__k8s__runtime-bundle-secret/instances/<instance>.json"

Check the in-cluster secret:

KUBECONFIG="$HOME/.hybridops/envs/dev/state/kubeconfigs/gke-burst.yaml" \
kubectl -n academy get secret academy-website-runtime -o yaml

Success indicators:

  • module state is status=ok
  • cap.k8s.runtime_bundle_secret = ready
  • bundle_sha256 is present in state
  • restarted_targets is populated when a changed bundle triggered a rollout restart
  • the Kubernetes Secret exists under the expected namespace and name

Destroy

hyops destroy --env dev \
  --module platform/k8s/runtime-bundle-secret \
  --state-instance burst_runtime_proof \
  --inputs /path/to/inputs.yml

Notes

  • This module syncs a file into Kubernetes; it does not build the bundle.
  • Workload secrets still belong in the normal secret-store flow (ExternalSecret, GSM, Workload Identity, and similar).
  • For the current burst path, this is the correct bridge for private runtime payloads that must stay outside the public workload baseline.
  • When restart_targets is set, HyOps compares the previous hyops.bundle-sha256 annotation with the new bundle and only restarts the named workloads when the bundle actually changed.

References