Postgres 17 Upgrade

This guide will walk you through the process of migrating a FOSSA-managed Postgres database (version 11.8) to a standalone Postgres 17.x instance. For customers deploying databases within Kubernetes, we provide example steps using the latest Postgres Helm chart version 2.0.0, but any properly configured Postgres 17.x database is supported.

FOSSA Postgres Helm Chart Deprecation

After June 16, 2025, FOSSA will no longer bundle a Postgres database within the FOSSA Helm charts. Customers who currently rely on the built-in provisioned Postgres instances (postgres.provisionInstance, hubble.postgres.provisionInstance, or sparklePostgres.provisionInstance) will need to migrate to an externally provisioned Postgres 17 database to continue receiving updates.

For customers running Postgres inside their Kubernetes cluster, we recommend using the fossa/postgres 2.0.0+ Helm chart as a convenient and tested deployment method. However, any properly configured Postgres 17.x database — including Amazon RDS, Aurora Postgres, or self-managed Postgres 17 — is supported.

Prerequisites

• postgresql client 17.x
  • postgres 17.2
• helm 3.17+
• kubectl 1.28+
  • Kubernetes API access
• fossa helm charts
  • postgres helm chart version2.0.0 from fossa/postgres
  • https://docs.fossa.com/update/docs/1-2#/
• quay pull secrets

Recommendations

• The default resource values for database deployments match FOSSA Core’s default settings. If your application has customized resource requirements, please adjust the database configuration files accordingly.
• If you use external Postgres services (e.g., RDS or self-hosted instances), ensure that:
  • Required extensions (such as pgcrypto, uuid-ossp) are available.
  • Your database instance is reachable from the FOSSA application. (SSL is not currently supported.)
  • Authentication credentials and roles allow schema migrations.
• If your vulns updater is disabled, you can ignore the associated configuration steps in this guide.

Assumptions

• Your Helm release is named fossa.
• Database credentials are:
  • fossa / fossa123 for Core
    • Service:
      • Old database: fossa-core-postgres
      • New database: postgres-core
  • fossa / fossa123 for Sparkle
    • Service:
      • Old database: fossa-sparkle-postgres
      • New database: postgres-sparkle
  • fossa / fossa123 for Hubble
    • Service address:
      • Old database: fossa-sparkle-postgres
      • New database: postgres-hubble
• Resource settings align with Core’s defaults unless otherwise specified.
• Vulns updater is enabled (unless noted otherwise).
• Quay.io pull secrets:
  • username: fossa+customer
  • password: HELLOWORLD1

Migration Steps

Install and Update Fossa Helm Charts repository

helm repo add fossa https://charts.fossa.com
helm repo update

Set namespace

1. Set the namespace to fossa

kubectl config set-context namespace=fossa

Create values files for each database

2. Create a new values file for core, sparkle and hubble databases with the appropriate auth credentials and database resources for the Postgres chart.

Core core-psql-values.yml

database: fossa
username: fossa
password: fossa123
image.registry: quay.io
image.repository: fossa/postgres
image.tag: 17.2-1

imageCredentials:
	username: fossa+customer
	password: HELLOWORLD1

resources:
  limits:
    cpu: 4000m
    memory: 4Gi
  requests:
    cpu: 2000m
    memory: 4Gi

Sparkle sparkle-psql-values.yml

database: sparkle
username: fossa
password: fossa123
image.registry: quay.io
image.repository: fossa/postgres
image.tag: 17.2-1

imageCredentials:
	username: fossa+customer
	password: HELLOWORLD1

resources:
  limits:
    cpu: 4000m
    memory: 4Gi
  requests:
    cpu: 2000m
    memory: 4Gi

Hubble hubble-psql-values.yml

database: hubble
username: fossa
password: fossa123
image.registry: quay.io
image.repository: fossa/postgres
image.tag: 17.2-1

imageCredentials:
	username: fossa+customer
	password: HELLOWORLD1

resources:
  limits:
    cpu: 4000m
    memory: 4Gi
  requests:
    cpu: 2000m
    memory: 4Gi

Install the Postgres helm chart from fossa/postgres for each database

3. Install the Postgres chart using the new values file for core, sparkle and hubble databases.

helm upgrade -i postgres-core fossa/postgres --values core-psql-values.yml
helm upgrade -i postgres-sparkle fossa/postgres --values sparkle-psql-values.yml
helm upgrade -i postgres-hubble fossa/postgres --values hubble-psql-values.yml

Set the application to maintenance mode

4. Set the application to maintenance mode.

helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=true --set vulns.updater.enabled=false --reuse-values

If your vulns updater is disabled, please ignore the vulns updater parameters and set the maintenance mode to true as follows:

helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=true --reuse-values

Create database backups

5. Make a backup of core, hubble and sparkle fossa databases and terminate the port-forward upon completion.

Core

### Core
kubectl port-forward service/fossa-core-postgres 5432:5432 &
pg_dumpall -h localhost -U fossa -f fossa-core-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg

Sparkle

kubectl port-forward service/fossa-sparkle-postgres 5432:5432 &
pg_dumpall -h localhost -U fossa -f fossa-sparkle-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg

Hubble

kubectl port-forward service/fossa-hubble-postgres 5432:5432 &
pg_dumpall -h localhost -U fossa -f fossa-hubble-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg

Restore database backups

6. Restore the fossa database from the backup for core, hubble and sparkle databases.

Core

### Core
kubectl port-forward service/postgres-core 5432:5432 &
psql -h localhost -U fossa -d fossa -f fossa-core-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg

Sparkle

kubectl port-forward service/postgres-sparkle 5432:5432 &
psql -h localhost -U fossa -d sparkle -f fossa-sparkle-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg

Hubble

kubectl port-forward service/postgres-hubble 5432:5432 &
psql -h localhost -U fossa -d hubble -f fossa-hubble-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg

Check the health of the databases

7. Ensure the core, sparkle and hubble databases are running and healthy.

kubectl logs sts/postgres-core -f
kubectl logs sts/postgres-sparkle -f
kubectl logs sts/postgres-hubble-f

Update the applications

8. Update the release to use the new Postgres 17.2 databases.

Core

helm upgrade -i fossa fossa/fossa-core --set postgres.host=postgres-core --reuse-values

Sparkle

helm upgrade -i fossa fossa/fossa-sparkle --set sparklePostgres.host=postgres-sparkle --reuse-values

Hubble

helm upgrade -i fossa fossa/fossa-hubble --set hubble.postgres.host=postgres-hubble --reuse-values

Set the application to production mode

9. Set the application to production mode

helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=false --set vulns.updater.enabled=true --reuse-values

If your vulns updater is disabled, please ignore the vulns updater parameters and set the maintenance mode to false as follows:

helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=false --reuse-values

Ensure the application is healthy

10. Ensure the application is running and healthy.

kubectl logs deployment/fossa-fossa-core-api -f
kubectl logs deployment/fossa-fossa-core-workers-primary -f
kubectl logs deployment/fossa-fossa-hubble-api -f
kubectl logs deployment/fossa-fossa-core-sparkle-api -f

Update your main values file

11. Finally after confirming the applications are running and healthy, update your values file to use the new databases.

Core

postgres:
  host: postgres-core

Sparkle

sparklePostgres:
  host: postgres-sparkle

Hubble

hubble:
  postgres:
    host: postgres-hubble

Note on External Databases

If you are connecting FOSSA Core to an external Postgres 17.x service such as Amazon RDS, Aurora, or self-hosted Postgres:

• You do not need to deploy Postgres helm charts.
• You should update your FOSSA Helm values to point to the appropriate external database hostnames.
• Ensure proper firewall/endpoint access between FOSSA pods and your database.
• Ensure required extensions (pgcrypto, uuid-ossp) are enabled.
• Review resource sizing and connection pool settings to ensure application performance.

Example snippet for an external RDS database:

postgres:
  host: your-rds-endpoint.amazonaws.com
  username: fossa
  password: your-fossa-password
  database: fossa

Repeat similar configurations for Sparkle and Hubble if those services are deployed.

Final Verification

Once all updates are complete:

• Ensure all FOSSA pods are healthy.
• Verify schema migrations completed successfully.
• Confirm that FOSSA Core, Sparkle, and Hubble services are operating normally.
• Confirm that the same data prior to the upgrade is still available by accessing your web interface