Skip to content

Replace Bitnami PostgreSQL with CloudNative-PG (CNPG)#524

Open
jlav wants to merge 11 commits into
mainfrom
jl/cnpg-migration-clean
Open

Replace Bitnami PostgreSQL with CloudNative-PG (CNPG)#524
jlav wants to merge 11 commits into
mainfrom
jl/cnpg-migration-clean

Conversation

@jlav
Copy link
Copy Markdown
Contributor

@jlav jlav commented Apr 6, 2026

Description

Resolves #250

Replace the Bitnami PostgreSQL Helm subchart with CloudNative-PG (CNPG) for managing PostgreSQL instances.

Bitnami has changed their licensing model. Their charts and images now require a paid subscription, and only the latest tag is available for development purposes. We are currently using legacy versions of their images (bitnamilegacy/postgresql). CNPG is an open-source, Kubernetes-native PostgreSQL operator that is actively maintained and CNCF-certified.

This is a breaking change. Existing embedded PostgreSQL data will not be migrated. Consumers using embedded PostgreSQL will need a fresh install.

Additionally, I've removed the embedded postgres option from all the charts except for openhands. Internally, we only ever use the parent chart's postgres instance and pass connection details down into the subcharts. It's a nice simplification of the subcharts to remove embedded postgres, but it does mean that the subcharts can no longer be deployed in a standalone way. Because we only ever exercise the parent chart's embedded postgres, I'm not confident that the subcharts are well tested on their embedded postgres, and I'd like to remove the burden of having to validate and maintain that path.

The new standard database configuration options for all the charts looks like this:

  # PostgreSQL database configuration
  database:
    # Hostname of the PostgreSQL server
    host: "..."
    # Port of the PostgreSQL server
    port: "5432"
    # Database user
    user: "..."
    # Database name
    name: "..."
    # Name of the Kubernetes secret containing the database password
    secretName: "..."
    # Key within the secret that holds the password
    secretKey: "..."
    # Create the database if it does not exist
    createDatabases: false
    # Run database migrations on startup
    migrate: true

Helm Chart Checklist

  • I have updated the version field in Chart.yaml for each modified chart
  • I have tested the chart upgrade path from the previous version
  • I have verified backwards compatibility with existing values.yaml configurationsN/A: this is an intentional breaking change
  • I have updated the chart's README.md if there are any breaking changes or new required values

Test Results

Fresh install on Replicated embedded cluster (instance-1) — PASS

Admin Console Dashboard

dashboard-ready

App Home

app-home

Test Conversation

test-conversation

Additional Notes

  • Customers using external PostgreSQL are unaffected — the external_postgres config path still works as before, just with the CNPG cluster disabled
  • Database creation is handled by init containers (not CNPG bootstrap), consistent with the existing pattern

jlav added 4 commits April 6, 2026 10:29
Migrate from the Bitnami PostgreSQL Helm subchart to CloudNative-PG
operator for managing PostgreSQL instances. This is a breaking change
that does not include data migration from existing installations.

- Create new `infra` chart with CNPG operator as subchart, installed
  at Replicated weight 5 to ensure CRDs are available before the
  openhands chart
- Add CNPG Cluster CR template to openhands chart, creating the
  `oh-main-postgresql` cluster with service `oh-main-postgresql-rw`
- Remove Bitnami PostgreSQL dependency from openhands, runtime-api,
  and automation charts
- Simplify runtime-api to receive DB connection details via env vars
  from the parent chart instead of managing its own PostgreSQL
- Add unconditional wait-for-db and create-db init containers to the
  automation chart
- Update all service references from `oh-main-postgresql` to
  `oh-main-postgresql-rw`
- Update Replicated configs, support bundles, and status informers
- Reuse existing `postgres-password` secret for CNPG superuser access
Fixes ImagePullBackOff on CNPG pods by passing the chart's
imagePullSecrets (including the Replicated registry secret)
to the Cluster spec.
The CNPG operator pod was hitting ImagePullBackOff because it was
attempting anonymous pulls from the Replicated proxy, which requires
authentication. Add the Replicated ImagePullSecretName to the
cloudnative-pg imagePullSecrets.
- openhands: 0.3.11 → 0.4.0
- runtime-api: 0.2.6 → 0.3.0
- automation: 0.1.0 → 0.2.0
@jlav jlav force-pushed the jl/cnpg-migration-clean branch from 38ab36a to ddee502 Compare April 6, 2026 14:49
The runtime-api dependency rewrite step was running helm dependency
update before the automation dependency version was rewritten,
causing it to fail when both subcharts had version bumps. The
dependency update at line 179 already runs after both rewrites.
@jlav jlav marked this pull request as draft April 6, 2026 18:01
jlav added 2 commits April 6, 2026 15:10
…harts

Consolidate scattered database connection settings into a consistent
`database` section in values.yaml for all three charts. This replaces
the old pattern of setting DB connection details via env vars or split
cnpg/externalDatabase configs.

- openhands: merge cnpg credentials, externalDatabase, and
  databaseMigrations into `database.*`
- runtime-api: move DB host/user/name from env map + helpers into
  `database.*`, merge databaseMigrations
- automation: remove unused createDatabaseUser feature and associated
  init container
@jlav jlav marked this pull request as ready for review April 7, 2026 17:49
jlav added 4 commits April 7, 2026 14:16
…tern

Resolve merge conflicts with main and incorporate the new
waitForDatabase toggle (from #534) into our standardized database
config pattern using the `database` key rather than `databaseMigrations`.

- Add database.waitForDatabase (default: true) to openhands, runtime-api,
  and automation charts
- Guard wait-for-db init containers with the new flag in all three charts
- Keep our branch's chart versions (openhands 0.4.0, runtime-api 0.3.0)
Step-by-step guide for migrating from Bitnami PostgreSQL to
CloudNative-PG with zero data loss. Uses PVC-based pg_dumpall/restore
to avoid kubectl streaming timeouts on large databases.
Copy link
Copy Markdown
Contributor

@aivong-openhands aivong-openhands left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see SaaS uses external DBs and there's already a migration guide here. LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Replace Bitnami PostgreSQL chart with CloudNativePG operator

2 participants