Forem: Yoni Gofman

Zero-Downtime Argo CD Migrations: The Ultimate Guide to ApplicationSet Refactoring

Yoni Gofman — Sat, 28 Mar 2026 12:15:40 +0000

In a GitOps world, your ApplicationSet is the source of truth for your fleet. But what happens when you need to rename a set, refactor your generators, or migrate workloads to a completely new Kubernetes cluster?

The default behavior of Argo CD is Cascading Deletion: delete the parent (AppSet), and you delete the children (Applications) and the grandchildren (K8s Resources). In production, this is a nightmare.

This guide covers how to bypass the "Delete-everything" trap using the Orphan Strategy for three real-world scenarios.

1. The Foundation: The "Orphan" Safety Net

Before performing any migration, you must ensure that deleting the ApplicationSet doesn't trigger a cleanup of your production environment.

Add this to your ApplicationSet spec:

spec:
  syncPolicy:
    preserveResourcesOnDeletion: true

What this does: It tells the controller to remove the ApplicationSet and the Application CRDs but leave the actual Kubernetes resources (Deployments, Services, etc.) running in the cluster.

2. The Pruning Pitfall: Don't Let Self-Heal Kill Your Migration

This is the most critical part of the migration. If your Root App or ApplicationSet has Prune: true and SelfHeal: true enabled, Argo CD will try to delete anything that doesn't match the Git state the second you make a change.

Senior Strategy:

Disable Pruning Temporarily: Before starting the migration, set prune: false in your SyncPolicy.
Verify via Dry-Run: Use the CLI to see what would be pruned: argocd app sync <app-name> --dry-run --prune
Use PrunePropagationPolicy=orphan: If you are deleting via kubectl, you can specify the propagation policy to ensure resources aren't reaped.

3. Scenario A: In-Place Refactoring (Renaming/Repo Change)

Use this when you want to rename an AppSet or move its definition to a different Git repository without causing downtime.

Step-by-Step:

Patch the Existing Set: Apply the preserveResourcesOnDeletion: true patch.
The "Detachment": Delete the old ApplicationSet.
- Result: Your Applications will now appear in the Argo CD UI as "Orphans".
Deploy the New Set: Create the new ApplicationSet. Ensure the template generates Applications with the exact same name as the orphaned ones.

Pro-Tip: Use Server-Side Apply (SSA)
To avoid metadata conflicts when the new manager takes over, enable SSA in the template:

spec:
  template:
    spec:
      syncPolicy:
        syncOptions:
          - ServerSideApply=true

4. Scenario B: Target Cluster Migration

Use this when you are moving workloads from an old cluster to a brand new one.

The Strategy: Side-by-Side Provisioning

Dual-Targeting: Update your generator to include both the old and the new cluster.
Avoid Collisions: Ensure your application names include the cluster name (e.g., name: '{{cluster}}-{{app}}') to keep them unique.
The Cut-over: * Verify the new cluster is Healthy.
- Switch your DNS/Traffic to the new cluster.
- Remove the old cluster from the generator. The preserveResourcesOnDeletion flag will keep the old apps as orphans until you're ready to manually delete them.

5. Scenario C: The "App of Apps" Hierarchy

When a Root App manages your ApplicationSet, you have a three-layer deletion chain.

Breaking the Chain

Orphan the AppSet: Delete the Root App using the --cascade=false flag via the CLI:
```
argocd app delete root-app --cascade=false
```
Disable Root-Level Pruning: Ensure the new Root App is deployed with prune: false for the first sync to prevent it from cleaning up the existing AppSet if there's a minor naming mismatch.
Re-parenting: Once the new Root App "adopts" the AppSet, you can safely re-enable pruning.

Senior Level Checklist

Finalizers: Check for resources-finalizer.argocd.argoproj.io. If it's there and you don't use the orphan flags, resources will be deleted.
Ignore Scaling Drift: Use ignoreDifferences for replicas to prevent the migration from resetting your production scale.
Sync Strategy: Always start with Manual Sync during a migration. Only switch back to Automated once you've verified the adoption.

Summary Runbook

Disable Pruning on the Root/Parent level.
Patch preserveResources on the AppSet.
Decouple (use cascade=false).
Deploy the new definition & Verify via Dry-run.

Stop Rebuilding Frontends for Every Environment

Yoni Gofman — Fri, 27 Mar 2026 14:57:31 +0000

As a DevOps engineer, one frontend problem has always felt unnecessarily expensive to me:

You build once for staging, then rebuild again for production because the frontend baked environment variables into the bundle.

Same app. Same code. Different environment. Another build.

That works, but it breaks one of the cleanest deployment ideas we have: build once, promote the same artifact everywhere.

So I built clientshell.

It lets you inject public runtime config into already-built frontend apps at container startup, without rebuilding for every environment.

Docs: https://yonigofman.github.io/clientshell/

The problem

Most frontend tooling treats environment variables as build-time values.

That means if your app needs a different API URL, feature flag, analytics key, or public tenant setting in another environment, the artifact changes. So your pipeline ends up doing this:

build for dev
build for staging
build for prod

From a DevOps point of view, that is friction.

It makes deployments slower, introduces more room for drift, and weakens the "immutable artifact" model that works so well in modern delivery pipelines.

What I wanted instead

I wanted a flow like this:

Build the frontend once
Ship the same static bundle everywhere
Inject environment-specific public config at runtime
Keep the frontend DX typed and predictable

That is what clientshell does.

What clientshell is

clientshell is a small toolchain for runtime public config in frontend apps.

It has a few pieces:

@clientshell/core for defining and reading typed public config
@clientshell/zod if you want to define the schema with Zod
@clientshell/vite, @clientshell/webpack, and @clientshell/rollup plugins
@clientshell/cli for manifest generation and validation
a fast Go-based injector for container startup

The idea is simple:

define a schema in TypeScript
generate a manifest during build
inject values into /env-config.js at runtime
read them in the browser with a typed API

Why this matters in DevOps

This project came from a DevOps mindset more than a frontend one.

The main benefit is not just convenience. It is deployment discipline.

With runtime injection:

the same image can go to staging and production
environment differences move to runtime config, not build logic
CI pipelines get simpler
rollbacks are cleaner
supply chain and provenance story improves because you publish fewer environment-specific artifacts

In other words: your frontend starts behaving more like a real deployable artifact.

A simple example

Define your public config shape once:

import { defineSchema, string, boolean } from "@clientshell/core";

export const clientEnvSchema = defineSchema({
  API_URL: string({ required: true }),
  ENABLE_BETA: boolean({ defaultValue: false }),
});

Use it in your app:

import { readEnvFromShape } from "@clientshell/core";
import { clientEnvSchema } from "./env.schema";

const env = readEnvFromShape(clientEnvSchema);

console.log(env.API_URL);

At build time, clientshell creates a manifest.

At runtime, the injector reads environment variables and serves the generated config to the browser.

No rebuild required.

Why not just use `window.ENV`?

You can. A lot of teams do.

But that usually turns into custom glue code, ad hoc scripts, inconsistent schema handling, and no real validation story.

What I wanted was something more structured:

typed schema
clear manifest format
bundler support
runtime injection
container-friendly behavior
CLI support for validation and generation

So instead of one more shell-script-on-top-of-nginx setup, this became a small, focused toolchain.

Where it fits

I think clientshell is especially useful for teams that:

deploy the same frontend artifact across multiple environments
use Docker heavily
want stronger separation between build and deploy phases
care about typed public config
are tired of environment-specific frontend rebuilds

If you are running Vite, Webpack, or Rollup-based apps and you want cleaner promotion pipelines, this is exactly the use case.

Docker example

The runtime model works especially well with containers.

A typical flow looks like this:

# 1. Build the app
FROM node:20-alpine AS builder
WORKDIR /app
COPY . .
RUN pnpm install && pnpm build

# 2. Runtime image
FROM clientshell
COPY --from=builder /app/dist /app/dist

Then at runtime:

docker run -p 9000:9000 \
  -e CLIENTSHELL_PORT=9000 \
  -e CLIENT_API_URL=https://api.example.com \
  my-app

That is the piece I like most.

You stop coupling deployment environment to bundle generation.

A note on DX

I did not want this to feel like a DevOps-only hack bolted onto frontend apps.

So the project keeps frontend ergonomics in mind too:

schema is typed
browser-side API is clean
Vite integration is straightforward
there is a Zod adapter if that is your preferred pattern
local development still works with stubbed config

So the frontend team does not need to fight the delivery model just because the platform team wants cleaner deployments.

Why I built it

Honestly, because I got tired of treating frontend config as if it had to be frozen at build time.

Backend and platform engineers have had better separation between build and runtime for a long time. Frontend delivery often lags behind there.

I wanted something small, explicit, typed, and deployment-friendly.

That became clientshell.

If this sounds familiar

If you have ever thought:

"Why am I rebuilding the exact same frontend just to change one public URL?"

then this project is for you.

Project

GitHub: https://github.com/yonigofman/clientshell