Migrating Superset from the Helm chart to the Kubernetes Operator

Moving a Helm-based Apache Superset to the Kubernetes Operator keeps the same superset_config.py but changes how secrets, the metadata database, cache and routing are owned. This page explains the sequence, effort drivers and the risks that matter.

On this page

What a Helm to Kubernetes Operator migration of Superset involves

Moving a Superset deployment from the official Helm chart to the Apache Superset Kubernetes Operator is a change of deployment owner, not a rebuild. The application, its superset_config.py and its metadata already exist, and the operator's migration guide describes a custom resource that reads the same configuration file. What determines effort is how much state the chart bundled: if it ran PostgreSQL, Redis or Valkey inside the release, you must provision those services outside it first, and the more secrets and overrides the chart carried, the more you have to copy and verify. The Superset documentation now marks the Helm chart as deprecated for new deployments and points to the operator, so the question for most teams is when to move, not whether.

The reference point for this guide is Helm chart 0.15.5, which carries appVersion 5.0.0. Check your deployed chart version and appVersion before you plan, because the migration steps assume that baseline. The operator itself is in alpha, with a v1alpha1 API whose custom resource schemas may change between releases. Treat the custom resource manifest as code you pin to a specific operator release, test on a staging cluster, and review again at every operator upgrade. Confirm with the project which operator release you will deploy and whether its schema changes are documented for the version you choose.

We do not estimate durations here because the answer depends on the inputs your team controls: the number of bundled components, the size of the metadata database, how many overrides live in Helm values, whether Celery workers and beat run in the same release, and how much staging validation your change process requires. A scoped assessment of your current release, values and secrets is the fastest way to turn those inputs into a written plan and quote. Ask any partner, including DeployOpen, to base the scope on a review of your actual release, and expect fixed deliverables and a cutover plan in writing before work starts.

Which Superset Helm values map cleanly to the operator

This table compares the main things the Helm chart manages with their operator equivalent and flags where the move needs rework or confirmation. Read the first column as the chart item you run today, then check the migration notes before changing anything. The main takeaway is that superset_config.py carries over, while the metastore, cache and Secrets need decisions before the release is removed.

Chart-managed itemOperator equivalentMigration notes
superset_config.pyRead by the operator from the same file, per the migration guideCarries over largely unchanged. Confirm that config referencing chart service names or chart-generated values is updated.
Bundled PostgreSQL metastoreNot managed by the operator; you provision and run itProvision external PostgreSQL first, back up the existing database and point the config at it before cutover.
Bundled Redis or ValkeyNot managed by the operator; you provision the cacheProvision external Valkey or Redis if the chart bundled it. Decide whether cache state needs to move or can be rebuilt.
Chart-owned SecretsLong-lived Kubernetes Secrets you create and referenceCopy needed values such as SECRET_KEY into Secrets you own, since chart-owned Secrets may be removed with the release.
Migration hook (runs every upgrade)Lifecycle tasks run in reconciliation when their inputs changeConfirm which tasks fire on first reconcile. Do not assume the operator reruns database upgrades on each change.
Ingress and routingRouting handled by the operator, per the migration guideConfirm the resource type and host rules against the operator documentation. Switch traffic only after the new deployment serves requests.
Replica scalingScaling handled in the reconciliation loopConfirm field names against the v1alpha1 schema, since alpha schemas may change between releases.

Documented paths the operator migration uses

The primary documented path is the Apache Superset Kubernetes Operator migration guide for moving from the Helm chart. It describes a Superset custom resource that reads the same superset_config.py the chart produced, while migrations, initialization, scaling and routing run in a reconciliation loop. Your plan should follow its order, because the guide assumes the new deployment serves traffic before the old release is removed.

  • Chart version baseline: The guide starts from Helm chart 0.15.5, which maps to appVersion 5.0.0. Confirm your running release against that baseline before you copy any values.
  • External services first: If the chart bundled PostgreSQL or Redis, provision external replacements before the cutover.
  • Long-lived Secrets: Copy the values you need into Kubernetes Secrets you own, since chart-owned Secrets may be removed with the release.
  • Operator alpha status: The operator is alpha with a v1alpha1 API, so confirm the custom resource schema for the version you install.
  • Removal order: Delete the Helm release only after the operator deployment serves traffic.

Check the guide against the exact operator and chart versions in your cluster before you write manifests.

Sequence for moving from the Helm release to the operator

The sequence moves a running Helm-based Superset onto the Superset custom resource without losing metadata, secrets or traffic, and ends with the Helm release removed only after the operator deployment serves requests. Each step closes with a check the team can verify before moving on.

  1. Inventory the release values and bundled components

    Export the values the Helm release currently uses, along with the rendered superset_config.py and any extra Secrets or ConfigMaps the chart references. Record which PostgreSQL and Redis or Valkey instances the chart deployed itself, since those become external dependencies you must provision. The team lead and platform engineer own this inventory. It is complete when every bundled component has a named owner, every secret key the application reads is listed by name, and nothing in the release is left unaccounted for.

  2. Back up the metadata database before any change

    Take a verified backup of the Superset metadata database before you touch the release, the Secrets or the cluster. Confirm that a restore works in a non-production environment, because the upgrade documentation calls for a backup before running database migrations. Record the backup location, time and the Superset version it reflects. The database administrator signs off. The step is done when a test restore completes and the team can name the backup it would use to roll back.

  3. Provision external PostgreSQL and Valkey or Redis

    If the chart bundled the metadata database or cache, stand up external services that the operator deployment can reach. The Superset configuration documentation lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x as supported metadata databases, so confirm your chosen version against that list. For the cache, Valkey is an open-source option compatible with Redis OSS 7.2 clients. Copy data into the new instances using the method that fits your source version, and confirm that the application connects from the cluster. The platform team owns this step and the check is a successful connection test from a test pod.

  4. Copy needed values into long-lived Secrets

    Create Kubernetes Secrets that you own directly, not through the chart, for the SECRET_KEY, database credentials, cache credentials and any OAuth or LDAP bind values. The migration guide warns that chart-owned Secrets may be removed along with the release, so this step prevents losing the key that encrypts stored connection data. Keep the SECRET_KEY value identical to the running deployment. Restrict read access with least-privilege RBAC and confirm that encryption at rest is configured for the cluster. Done when the Secrets exist, a value comparison matches the release and access is limited to the service accounts that need it.

  5. Stage the custom resource with the same superset_config.py

    Deploy the Superset custom resource in a separate namespace or with a different name, pointing it at the same superset_config.py and the Secrets from the previous step. The operator reads the same configuration file, so the goal is a byte-for-byte equivalent config with only connection targets changed. Keep this deployment out of user traffic. The platform engineer confirms the operator reports the resource healthy and that the application answers an internal health request. Note that the operator is in alpha with a v1alpha1 API whose schemas may change, so pin the operator version you tested.

  6. Test lifecycle tasks on first reconcile

    On the first reconcile, the operator runs migrations, initialization and other lifecycle tasks, and it runs each task only when its inputs change. The Helm hook, by contrast, reran on every upgrade. Watch the first reconcile in staging against a copy of the metadata database, and review which tasks ran and which were skipped. Confirm that a later change to a relevant input triggers the expected task. The check is a clean run log, a database schema that matches the Superset version, and a documented list of tasks that the team expects on future changes.

  7. Cut routing to the operator deployment

    Move ingress or the service route from the Helm-managed service to the operator deployment in a controlled window. Keep the Helm release running so traffic can return to it if a problem appears. Verify login, dashboard rendering, SQL Lab queries, and any scheduled reports or async work that depends on the worker and cache components. Watch error rates and logs for a period the team agreed in advance. The step is done when the operator deployment serves production traffic and the team has signed off on the functional checks.

  8. Remove the Helm release last

    Only after the operator deployment has served traffic and the rollback path is no longer needed, uninstall the Helm release. Before uninstalling, confirm that every Secret the application uses is owned outside the release and that no remaining workload depends on chart-managed resources. Retain the pre-migration backup under your normal retention policy. The platform lead records the final state, including operator version, Superset version and the backup reference. The sequence is complete when the release is gone, the operator serves traffic and the documented state matches the cluster.

How lifecycle tasks change between Helm hooks and reconciliation

The most important behavioral change in this move is when database work runs. The Helm chart uses a hook that reruns on every upgrade, so migration and initialization steps fire whenever the release changes. The Superset Kubernetes Operator runs its lifecycle tasks only when their inputs change, as described in the operator migration guide. For a team moving an existing deployment, this means the first reconcile against a metadata database that already holds dashboards, users and roles should not be treated as a routine upgrade. Before the cutover, confirm with the operator documentation exactly which inputs trigger the database upgrade and initialization tasks, and whether a change to the image tag, the superset_config.py source or the database connection counts as one of them.

The documented steps underneath both approaches are the same. Superset's upgrade guidance says to back up the metadata database, run superset db upgrade and then superset init, test in staging first, and check UPDATING.md for breaking changes between versions. The operator does not manage the metastore itself, so the backup, the restore plan and the choice of PostgreSQL or MySQL version (Superset's configuration documentation lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x) remain your responsibility. Plan a snapshot of the metadata database immediately before the first reconcile, and record the image version that last ran the Helm hook so you can explain any schema change afterward.

Treat the operator's task behavior as a point to verify, not a settled fact. The operator is in alpha with a v1alpha1 API whose schemas may change between releases, so the trigger rules could change too. Pin the operator version you tested, run the first reconcile in a staging copy of the production database, and confirm in that environment that no migration task runs when you expect it not to. Keep the Helm release in place until the operator deployment serves traffic and you have verified the database state, because the Helm hook is the rollback path you lose once the release is removed.

What drives the effort and cost of this migration

Does it cost more if our PostgreSQL and Redis run inside the Helm release?

Yes, usually, because bundled data services have to be provisioned as separate, managed services before the cutover can happen. The migration guide says to provision external PostgreSQL and Valkey or Redis if the chart bundled them, so that work is a prerequisite and not optional. The effort depends on whether you already run a managed PostgreSQL service and a Valkey or Redis service that your platform team supports. Ask any partner to separate the cost of provisioning and backing up these services from the cost of the operator migration itself. Provisioning is typically one-time, while backup, patching and monitoring of the services recur and stay with your team.

How does the number of environments change the migration effort?

Each environment needs its own inventory, values translation, Secrets, cutover rehearsal and rollback check, so effort grows with the count and with how different the environments are. A development cluster with a disposable metastore is much quicker than a production cluster with live dashboards and scheduled reports. Ask whether the quote covers each environment separately or a single reference environment that is then repeated, and whether staging is a true copy of production configuration. Environment count is a one-time cost for the migration, but every environment you keep afterward recurs as operating work.

Why do custom images and config overrides add to the migration work?

Custom images and config overrides add work because the operator reads the same superset_config.py as the chart, so every override and every installed driver or plugin must be carried across and tested. An image built with extra database drivers or custom plugins has to be rebuilt, scanned and referenced by the custom resource. Ask for an inventory of every override in your values file and every file mounted into the pod, and whether each one has a test that proves the setting still takes effect after the move. This work is one-time for the migration but the image build pipeline recurs with each Superset release.

Who should own the Kubernetes Secrets after the migration?

Your team should own them, and the migration should move every value that matters into long-lived Secrets that you control, because the guide warns that chart-owned Secrets may be removed with the release. The work is to identify the SECRET_KEY, database passwords, OAuth client secrets and cache credentials, then decide where they live and who can read them. The Kubernetes secrets good practices page notes that Secrets are stored unencrypted in etcd by default, so confirm whether encryption at rest is enabled and whether an external store is planned. Any partner quote should state who creates these Secrets, who holds the source values and how rotation will work after handover.

How do ingress and TLS changes affect the cutover schedule?

Routing changes are often the riskiest step because they decide when users reach the new deployment, so they need the most planning and the clearest rollback path. The guide says to remove the Helm release only after the operator deployment serves traffic, which means the old and new paths must both work for a period. Ask who manages DNS, certificates, the ingress controller and any load balancer, and whether certificate issuance or a new ingress class needs a change window. Confirm the number of hostnames, any websocket or long-running query paths and whether the old ingress can run in parallel. These steps are mostly one-time, although certificate renewal recurs.

How much does staging depth change the cost of the migration?

Staging depth changes cost more than any other single item because a shallow staging copy will miss problems that appear only with real data, real scheduled reports or real traffic. The Superset upgrade documentation recommends testing in staging first and backing up the metadata database before any change, so plan for a restore test as well as a deployment test. A deep staging setup needs a recent copy of the metadata database, matching external services and the same identity configuration. Ask the partner how many rehearsals the quote includes and what evidence each rehearsal produces. Staging infrastructure is partly recurring, since it must stay close to production as the platform changes.

Can our team do this migration without outside help?

Yes, if your team already runs Kubernetes workloads with Helm, manages Secrets and ingress, and can test restores, although the work still needs time from people who know the existing release well. The operator is in alpha with a v1alpha1 API whose schemas may change between releases, so your team must be ready to track changes and rework manifests. The Kubernetes version skew policy and release cycle also mean your cluster version must be supported by the operator and kept current. Ask an outside partner for a written scope that lists what they will deliver and what you must provide, so you can compare it honestly with an internal plan. Skill gaps in Kubernetes networking, etcd backup or Secret encryption are the usual reason internal efforts take longer than planned.

Where Helm to operator migrations usually go wrong

Most failed moves from the Helm chart to the operator come from a few avoidable decisions made early: where secrets live, which keys are carried over, and what the team assumes about an alpha project. The cards below cover each risk with the check that prevents it, so the cutover can be tested before traffic moves.

Chart-owned Secrets removed with the release

Secrets created by the Helm release can be deleted when the release is removed, which takes database passwords and other credentials with it. The migration guide asks you to copy the values you need into long-lived Kubernetes Secrets that the release does not own. Before you remove the Helm release, confirm that every credential the Superset custom resource references exists in a Secret you manage, and that the Pods still start after a test restart.

SECRET_KEY mismatch blocks existing data

Superset encrypts stored database connection passwords with SECRET_KEY, so a different value in the new deployment leaves existing encrypted data unreadable. Copy the exact key from the running Helm deployment into the new Secret before the first reconcile, and do not generate a new one. If you plan to rotate it, use PREVIOUS_SECRET_KEY as a separate, documented step after the cutover. Verify by opening an existing database connection in the new deployment.

Treating the alpha operator as stable

The Superset Kubernetes Operator is in alpha, and its v1alpha1 custom resource schemas may change between releases. A field that works today can be renamed in a later upgrade, which turns a routine operator update into a manifest rewrite. Pin the operator version, keep the custom resource manifests in version control, and read the release notes before every upgrade. Agree in advance how your team will respond if a schema change lands in a staging rollout.

Moving Valkey or Redis data unnecessarily

Superset uses the caching layer for async queries, alerts, reports and thumbnails, and much of that data is transient. In many installations, the right move is to deploy a new Valkey or Redis instance and let the cache rebuild, not to migrate keys. Before you plan a data move, confirm which cached items must survive the cutover and whether losing them only causes a cold cache. Check that scheduled reports still run after the switch.

Skipping Kubernetes version and readiness checks

The operator runs on your cluster, so its supported Kubernetes versions and the cluster's own version skew determine whether the deployment is stable. Kube-apiserver must be upgraded one minor version at a time, and kubelets may be up to three minor versions behind. Confirm the cluster version against the operator's stated requirements, check node health, and confirm that the PostgreSQL and cache endpoints are reachable from the new namespace before the first reconcile.

Routing cut over before the operator is ready

Changing the ingress or DNS to the new service before the operator deployment passes its health checks sends users to pods that may still be running migrations or failing to connect. The migration guide says to remove the Helm release only after the operator deployment serves traffic. Keep the old release running, switch routing in a single step, watch login and dashboard load, and keep a tested rollback path until the new deployment has run through a full working day.

Questions teams ask before moving off the Superset Helm chart

How much does moving Superset from the Helm chart to the Kubernetes Operator cost?

The cost depends on the written scope, not on a standard package. Most of the price comes from the work that touches your running system: inventorying what the Helm release owns, provisioning or confirming external PostgreSQL and Redis or Valkey, copying values into long-lived Secrets, translating overrides into the Superset custom resource, validating the first reconcile, and cutting over routing. Each of these is a line item you can ask about. One-time costs cover the migration itself and the staging rehearsal. Recurring costs, if you want them, cover operator upgrades, patch cycles and testing, which are usually handled through a retainer. DeployOpen does not publish prices, so ask for a quote built from a written scope that lists each of these items and states which environments are included.

How long does the migration take?

Duration depends on how many environments you run, how many overrides and secrets the chart carries, whether PostgreSQL and Valkey are already external, how much of the cluster needs changes, and how many approval steps your change process requires. A single production instance with clean overrides and existing external services is a very different project from a multi-environment deployment that still runs a bundled database. The migration guide frames the sequence as a parallel deployment that serves traffic before the Helm release is removed, so plan for a staging rehearsal and a period where both releases exist. Ask for a timeline in the written scope that ties each milestone to a deliverable.

What must our team provide before the engagement starts?

Your team needs to provide working access and decisions, not just a request. The main items are:

  • Cluster access with rights to create Secrets, deploy the operator and manage the Superset custom resource in the target namespace
  • A named owner for each Kubernetes Secret, including who rotates it and who approves changes
  • A staging or test environment that resembles production, with a copy of the metadata database
  • Current Helm values, the superset_config.py in use, and the list of images and ingress rules
  • Confirmed access to the external PostgreSQL and Valkey or Redis services, or a decision to provision them

Confirm the scope of each item in the written agreement so that gaps show up before cutover.

Can our internal platform team migrate Superset without a partner?

Yes, if your team has Kubernetes operations experience and time for a staged rehearsal. The work is well defined: the migration guide describes a reconciliation-based flow that reads the same superset_config.py, and the operator handles migrations and initialization in its loop. The harder parts are the ones teams underestimate: copying values out of chart-owned Secrets before the release is removed, confirming that lifecycle tasks run only when their inputs change, and proving that the new routing serves traffic before retiring the old release. Teams without these skills in-house often hire a partner for a fixed-scope migration and keep the platform internally. Compare your team's capacity against the written scope before deciding.

Is the Superset Kubernetes Operator safe to run in production?

Treat the operator as an alpha component and plan around that. The operator documentation states that it is alpha and uses a v1alpha1 API whose custom resource schemas may change between releases. That does not make it unusable, but it does mean that every operator upgrade needs a review of the release notes, a staging test against your custom resource manifests, and a pinned version in your deployment tooling. Also confirm how your organization handles alpha software in production under its risk acceptance process. The Helm chart is marked deprecated in current development documentation, so both paths carry some risk. Your engagement should record the accepted operator version and the upgrade procedure as deliverables.

Do we have to keep the SECRET_KEY and the existing data when we migrate?

Yes. Superset requires a user-specified SECRET_KEY to start, and the metadata database stores values that depend on it, so a new or changed key can make stored connection credentials unreadable. Keep the same key in a long-lived Kubernetes Secret before removing the Helm release, and check whether a PREVIOUS_SECRET_KEY rotation is in progress. Back up the metadata database before the first reconcile, and verify dashboards, datasets, database connections and users in the new deployment. The upgrade guide also advises running database upgrades in staging first. Record the key ownership and backup location in the written scope.

How is a fixed-scope engagement agreed in writing?

DeployOpen agrees the scope, deliverables and timeline in writing before work starts, and most engagements are fixed-scope. The written scope normally lists the environments covered, the external services to provision or confirm, the Secret inventory and ownership, the cutover approach, the verification steps, and the handover documentation. It also states your responsibilities, such as access, approvals and test data, because delays in those areas move the timeline. Ask for the scope to name what is excluded, including any upgrade, retainer or ongoing testing, so that later work is priced separately. DeployOpen does not issue audit reports or certifications, so any compliance evidence it prepares is delivered as readiness material for your assessor.

How DeployOpen scopes and delivers this migration

DeployOpen starts by reading your current Helm release, values files, Secrets and superset_config.py, then agrees a fixed written scope for moving that Superset onto the Superset custom resource. The build runs in your own cluster and cloud accounts, with the Helm release removed only after the operator deployment serves traffic.

How we scope

  • We inventory the Helm release, values overrides, chart-owned Secrets and any bundled PostgreSQL or Redis that must become external services.
  • The written scope names the metastore, cache, Secret ownership, config override approach, routing changes and cutover window before work starts.
  • Engagements are fixed-scope, and the quote follows from that written scope, with no list prices published.

How we build

  • We provision external PostgreSQL and Valkey or Redis, then copy required values into long-lived Kubernetes Secrets outside the Helm release.
  • We write the Superset custom resource to read the same superset_config.py, and verify lifecycle tasks run only when their inputs change.
  • We test the build in a staging namespace, including a metadata database backup and a rehearsed routing switch before production.

How we hand over

  • You receive the custom resource manifests, Secret inventory, routing configuration and a runbook for the cutover and rollback steps.
  • We document the Helm release removal sequence, so no chart-owned Secret is deleted while the operator deployment still depends on it.
  • We record the operator version and note that its v1alpha1 schemas may change between releases, so upgrades are planned against that.

How we support

  • Ongoing support, operator upgrades and continuous testing are available as a retainer after handover.
  • Upgrade work follows the Superset upgrade steps: back up the metadata database, run the migration commands, and test in staging first.
  • Confirm with DeployOpen before scoping how operator alpha changes, Kubernetes version support and Valkey upgrades will be handled.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.