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 item | Operator equivalent | Migration notes |
|---|---|---|
| superset_config.py | Read by the operator from the same file, per the migration guide | Carries over largely unchanged. Confirm that config referencing chart service names or chart-generated values is updated. |
| Bundled PostgreSQL metastore | Not managed by the operator; you provision and run it | Provision external PostgreSQL first, back up the existing database and point the config at it before cutover. |
| Bundled Redis or Valkey | Not managed by the operator; you provision the cache | Provision external Valkey or Redis if the chart bundled it. Decide whether cache state needs to move or can be rebuilt. |
| Chart-owned Secrets | Long-lived Kubernetes Secrets you create and reference | Copy 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 change | Confirm which tasks fire on first reconcile. Do not assume the operator reruns database upgrades on each change. |
| Ingress and routing | Routing handled by the operator, per the migration guide | Confirm the resource type and host rules against the operator documentation. Switch traffic only after the new deployment serves requests. |
| Replica scaling | Scaling handled in the reconciliation loop | Confirm 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.
The Superset configuration documentation governs what carries over unchanged. The operator reads the same superset_config.py, so application settings do not need a rewrite, but the values behind them must survive the move. The most sensitive value is SECRET_KEY, which Superset requires to start and which protects data it has already encrypted. Changing it without a plan can break access to stored database connection credentials.
- Reuse SECRET_KEY: Keep the existing value in the new Secret. Do not generate a new one during cutover.
- Rotation path: If rotation is needed,
PREVIOUS_SECRET_KEYsupports moving to a new key while older encrypted data stays readable. - Config overrides: Move environment-specific settings such as authentication and cache options into the configuration source the operator reads, and test each one.
- Metadata database settings: Point the connection at the external PostgreSQL or MySQL instance using the versions the configuration documentation lists.
- Authentication settings: Confirm OAuth2, LDAP and role mapping settings survive the move unchanged.
Record every key you change so the verification step can compare the old and new behavior.
The Superset upgrade documentation gives the sequence that protects the metadata database during any change of deployment. Although the migration is about deployment rather than a version change, the same backup and migration steps apply when the new deployment runs database migrations. Treat the metadata database as the record you must be able to restore.
- Back up first: Take a backup of the metadata database before the operator reconciles any migration task.
- Run database upgrade: The documentation uses
superset db upgradeto bring the schema in line with the code version. - Run initialization: Follow with
superset initso roles and permissions are set for the running version. - Stage the test: Run the sequence in staging against a copy of production data before touching production.
- Check breaking changes: Read
UPDATING.mdfor the target version, since it lists changes that affect configuration and data.
Confirm that your backup restores into a scratch database before you rely on it.
When the Helm chart bundled PostgreSQL and Redis or Valkey, the work is mostly provisioning. The bundled services ran inside the release, so their data and credentials need a new home before the chart is removed. The migration guide calls for external PostgreSQL and Valkey or Redis, and it warns that chart-owned Secrets may disappear with the release.
- Provision PostgreSQL: Create a managed or self-run PostgreSQL instance and restore the metadata database into it.
- Provision cache: Provide Valkey or Redis for caching, async queries and alerts or reports where those features are enabled.
- Move the data: Copy the bundled database contents with a dump and restore, and verify row counts or application behavior afterward.
- Rewrite connection values: Update host names and credentials in the long-lived Secrets.
- No vendor importer: The change is in deployment, not dashboard content, so no importer is needed.
Confirm the restored database matches the source before you point the operator at it.
When the Helm release already points to an external PostgreSQL and Redis or Valkey, the migration is narrower. The data layer stays where it is, and the work concentrates on Secrets, configuration and routing. The operator does not manage the metastore, so the existing database remains your responsibility.
- Reuse connections: Keep the same database and cache endpoints, and copy the credentials into long-lived Secrets.
- Confirm versions: Check that the metadata database version is within the range the configuration documentation lists.
- Still back up: Take the same backup and run the same
superset db upgradeandsuperset initsequence before cutover. - Check lifecycle tasks: Operator lifecycle tasks run only when their inputs change, unlike the Helm hook that reran on every upgrade, so confirm when migrations will run.
- No vendor importer: Dashboards, datasets and charts stay in the database, so nothing needs to be exported or imported.
Confirm the connections and Secrets reach the operator before you change any routing.
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.
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.
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.
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.
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.
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.
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.
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.
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.pyin 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.

