Migration Guides
This section documents breaking changes and migration steps for upgrading kubara across major or minor versions that require user intervention.
Migrating from v0.18.x to v0.19.0
Background & Responsibility Cleanup
In kubara v0.18.0 and earlier, configuration responsibilities were split between .env and config.yaml:
- Running
kubara init --prepwas required to scaffold an initial.envfile containing cluster parameters (PROJECT_NAME,PROJECT_STAGE, repository URLs, and credentials). - Running
kubara init(orkubara init --overwrite) copied those values from.envintoconfig.yaml, creating conflicting sources of truth. kubara generatehad access to.envin its templating context, introducing risk of secret leakage into generated Git manifests.
Starting with v0.19.0 (ADR-0005):
config.yamlis the sole source of truth for all platform and cluster configuration (cluster names, stages, repository URLs, DNS names, and service settings)..envis strictly optional and secret-only, restricted to bootstrap repository credentials (GITOPS_*,DOCKERCONFIG_BASE64, and optionalARGOCD_PASSWORD).- OS environment variables take precedence, allowing native CI/CD execution without writing a
.envfile to disk. kubara generateno longer reads.env, ensuring secrets cannot leak into Git manifests.kubara initis a single-step command that scaffoldsconfig.yaml,env.example, andrenovate.jsonwithout requiring--prepor--overwrite.
Migration Steps for Existing Repositories
If you maintain an existing repository initialized with kubara v0.18.0 or earlier:
-
Verify your
config.yaml: Ensure each cluster inspec.clustershas explicitname,stage, andargocd.repo.gitURLs. These are no longer read from.env. -
Clean up your
.env(if used): - Remove non-credential variables (
PROJECT_NAME,PROJECT_STAGE,ARGOCD_GIT_URL,ARGOCD_HELM_REPO_URL). - Rename any legacy
ARGOCD_GIT_*orARGOCD_HELM_*credential variables to theirGITOPS_*equivalents -
If you previously configured
ARGOCD_WIZARD_ACCOUNT_PASSWORD, rename it toARGOCD_PASSWORDor remove it entirely to let kubara autogenerate a secure password during bootstrap. -
Update CI/CD workflows:
- Remove
kubara init --prepandkubara init --overwriteflags from your pipelines.kubara initruns in a single step. - Update any pipeline environment variables from
ARGOCD_GIT_*toGITOPS_*. - Ensure
config.yamlmodifications in CI target the YAML file directly (e.g. via scripts oryq), rather than relying on.envoverrides.