Last modified November 6, 2026

App Platform deprecation and migration to Flux HelmRelease

The Giant Swarm App custom resource (App, in the application.giantswarm.io API group) is being phased out in favor of upstream Flux HelmRelease. Every Giant Swarm management cluster already runs Flux, and we’re now making it the recommended way for customers to deploy and configure applications.

Why we’re making this change

  • Standard upstream API. HelmRelease is a widely adopted upstream API. You can use the same tooling on Giant Swarm that you use elsewhere, with no proprietary CRD to learn.
  • More expressive feature set. HelmRelease offers dependency ordering (dependsOn), drift detection, post-renderers, fine-grained install/upgrade/rollback policies, and valuesFrom with explicit merge order. These features map onto things we’ve layered on top of App CRs over the years.
  • Simpler stack. Collapsing the Giant Swarm app-operator pipeline into one well-understood upstream controller reduces moving parts on the management cluster.

HelmRelease capabilities to know

These features either have no App CR equivalent or previously required custom tooling to approximate. See the upstream HelmRelease reference for the full specification.

  • Post-renderers. Apply Kustomize patches to a rendered chart so you can adjust upstream charts (image references, annotations, individual fields) without forking. Patches are persisted to the release, so drift detection accounts for them.
  • Drift detection. Opt-in via spec.driftDetection.mode: enabled (warn only reports). Then Flux reverts out-of-band changes (kubectl edit, console edits) back to the declared manifest on each reconcile, with ignore rules for fields that legitimately change at runtime.
  • Readiness-gated dependencies. dependsOn blocks a release until other HelmReleases report Ready. This solves the common case of installing a controller (and its custom resource definitions) before any custom resources that depend on it.
  • Configurable failure remediation. Declarative retry counts, choice of rollback or uninstall on failure, and cleanupOnFail, all surfaced as spec fields.
  • Flexible chart sources. Pull charts from HelmRepository, OCIRepository, GitRepository, or Bucket, including OCI references with SemVer ranges for controlled auto upgrades.

Timeline

Specific dates to be confirmed. Until the timeline is finalized:

  1. Phase 1: Communication and docs (completed)

    App Platform sunset announced with a long deprecation window. App Platform documentation moved to a legacy section and new tutorials default to Flux resources.

  2. Phase 2: Flux by default (completed)

    App Platform (App, AppCatalog, AppCatalogEntry, Catalog, Chart) are fully supported but new deployments should prefer the Flux resources.

  3. Phase 3: Resource migration (today)

    The migration CLI is available. App Platform reconciliation continues unchanged, so existing deployments keep working while you migrate them over to Flux.

  4. Phase 4: Sunset (~year)

    App Platform support ends. All workloads expected to run as Flux resources.

We update this page as the timeline is firmed up. If you’re planning a major deployment, contact your account engineer or support and we’ll factor your schedule in.

What this means for you

  • Existing App Platform resources keep working. There will be a long, supported overlap period, so don’t rush a migration.
  • For new deployments, use Flux resources. Start with Deploying an application via a Flux HelmRelease.
  • Plan a migration when it fits your release cadence. The migration CLI converts App Platform resources into Flux equivalents, one app at a time.

What’s affected

The following resource types in the application.giantswarm.io API group are part of the deprecation:

  • App
  • AppCatalog
  • AppCatalogEntry
  • Catalog
  • Chart

Their reference documentation remains available but will be marked as deprecated and link back to this page.

Migrating with the CLI

The appcr-to-helmrelease-converter CLI moves one App CR at a time to Flux. It reads the App CR and its Catalog from the management cluster and creates an OCIRepository (or a HelmRepository for a Helm catalog) and a HelmRelease with the same name, namespace and values. Its ConfigMap and Secret references become valuesFrom entries in the same order. Flux then takes over the Helm release the App CR installed, so the app isn’t reinstalled.

You need uv and kubectl access to the management cluster. The app must be deployed, as the CLI reads its live state.

First, set up the CLI. uvx runs it straight from the repository, without a clone. This alias keeps the commands short:

alias appcr-to-helmrelease-converter='uvx --from git+https://github.com/giantswarm/appcr-to-helmrelease-converter@main appcr-to-helmrelease-converter'

Then preview the Flux resources it generates for the App CR, here loki in org-acme:

appcr-to-helmrelease-converter migrate --name loki --namespace org-acme --dry-run --output loki-flux.yaml

Run it again without --dry-run to migrate. The CLI suspends the App CR, applies the Flux resources and waits for the HelmRelease to be ready. If it fails, the CLI offers to roll back.

If the App CR comes from a GitOps repository, replace it there with the resources in loki-flux.yaml and merge the change.

Finally, delete the App CR and its Chart CR from the cluster:

appcr-to-helmrelease-converter cleanup --name loki --namespace org-acme

cleanup checks that the HelmRelease is ready and that Flux manages it before it deletes anything. Note that it can’t check your GitOps repository. If the App CR is still there, Flux creates it again.

The CLI’s README describes every flag, for example for private catalogs and registry mirrors.

Clusters

The CLI can also move a cluster deployed with an App CR of a cluster chart, like cluster-aws, to a HelmRelease of the release chart, like release-aws. Giant Swarm is migrating its own clusters this way first, and this section will describe the steps once that’s done. If you want to migrate a cluster before then, ask your account engineer.

GitOps repositories created with kubectl-gs

Since kubectl-gs v5.13.0, kubectl gs template cluster renders clusters as a HelmRelease of the release chart. Newer versions of kubectl gs gitops add base and kubectl gs gitops add workload-cluster do the same and don’t support App CRs anymore. To keep using them on a repository created with an older version, upgrade the repository once its App CRs are gone:

  1. Migrate every app in the repository with the CLI, and every cluster as Clusters describes.

  2. Replace the cluster App CR in each cluster base with the OCIRepository and HelmRelease that kubectl gs gitops add base generates.

  3. Check which parts of the repository are outdated, then upgrade them:

    kubectl gs gitops check
    kubectl gs gitops upgrade
    

gitops upgrade rewrites the files kubectl-gs generated around the App CRs. The patch adding --cluster-user-config to the cluster then targets the HelmRelease, and the patch pointing App CRs at the workload cluster goes away. It fails on any part of the repository that still deploys an App CR and lists the files.

Giant Swarm also has an internal skill that drives the migration of an app across all your clusters, with the CLI doing each step. It works best on repositories that follow the gitops-template structure. If you’d like help with the migration, ask your account engineer.

Where to go next

If you have questions about the timeline or migration approach, reach out to your account engineer or to support.