Over time, the existing GitOps repository, especially the heavily used OpenShift deployment logic, had evolved into a collection of opaque scripts relying on Jinja templates and custom logic. These scripts handled staging/production image swaps and various environment-specific behaviors, but their complexity made them hard to maintain, hard to follow, and far from the declarative GitOps model they were intended to support. Moreover, all of this functionality lived in a fully private repository, further limiting transparency and reusability.

To address this, I introduced a redesigned architecture centered around Helm:

• A *new public Helm library* was created to encapsulate all custom templating logic. Some patterns carry over from the legacy flow while others were fully re-engineered for clarity and reusability.
• Each application now defines its own *public Helm chart* (extending the Helm library) alongside its source code, ensuring full transparency and a single source of truth per service.
• The private GitOps repo (for what regards Openshift Helm Charts) was simplified to contain *only values, secrets, and references to the Helm charts* that must be deployed. Existing scripts have been modified to include Helm support to make this possible.
• All legacy components remain intact to ensure a safe, controlled transition without disrupting existing deployments.

This new setup dramatically improves maintainability, declarativity, auditability, and long-term scalability of the entire deployment pipeline.

1. 1. 1. *Migration Plan*

Some team members raised concerns that the migration would never fully happen because no one would voluntarily work on it unless something breaks, and in those situations it feels “easier to just fix the old system.” Without a structured plan, this creates a deadlock: the legacy system keeps getting patched, the new system isn’t adopted, and technical debt continues to grow. A formal, enforced plan ensures the migration proceeds safely, predictably, and without relying on voluntary effort or spare time. It aligns incentives, removes fallback paths, and guarantees completion.

*1. Port All Legacy Templates to Helm*

• Every existing legacy template must be replicated or re-implemented in the new Helm library or in service-specific Helm charts
• Parity is required before deprecating any legacy component, ensuring functional equivalence

*2. Freeze the Legacy System*

• Legacy Jinja templates and scripts become read-only
• Only critical break-fixes are allowed, requiring approval and written justification
• No enhancements, new features, or environment-specific logic may be added
• CI prevents modifications to legacy templates unless explicitly approved

*3. Route All New Work Through Helm*

• Any bug fix, configuration change, feature update, secret addition, or environment modification must be performed using the Helm architecture
• This makes the new system the default path for all ongoing development

*4. Standard Migration Lifecycle (Per Service)*

1. Assess legacy usage and map behaviors to Helm equivalents
2. Create or update the service’s public Helm chart extending the shared library
3. Validate with manifest diffs
4. Migrate the service

*5. Long-Term Deprecation Timeline*

• Migration progresses incrementally through normal development activity
• When all services are migrated, the legacy system is formally removed

Jira: CKI-7092