FusionAuth - Control Plane

Overview

FusionAuth is a modern, self-hosted identity and access management platform that provides user authentication, authorization, and secure single sign-on. It supports OAuth2, OpenID Connect, and SAML. This template deploys FusionAuth with a PostgreSQL database that is automatically configured and connected — no manual database setup required.

What Gets Created

FusionAuth Workload — The main identity platform with configurable CPU and memory.
PostgreSQL Workload — The backing database, automatically connected to FusionAuth on startup.
Volume Set — Persistent storage for PostgreSQL data, with optional autoscaling.
Backup Cron Job (optional) — A scheduled job that dumps the PostgreSQL database to an S3 or GCS bucket when postgres.backup.enabled is true.
Secrets — An opaque PostgreSQL credentials secret, and a startup script secret that waits for database readiness before launching FusionAuth.
Identity & Policy — An identity bound to the workloads with reveal access to the PostgreSQL credentials and startup script secrets. When backup is enabled, the identity also provides the backup cron job with access to the configured object storage bucket.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

Prerequisites are only required if you plan to enable PostgreSQL backups (postgres.backup.enabled: true). Skip this section if backups are not needed.

AWS S3

Create an S3 bucket. Set postgres.backup.aws.bucket and postgres.backup.aws.region in your values file.
If you do not have a Control Plane Cloud Account set up, follow the Create a Cloud Account guide. Set postgres.backup.aws.cloudAccountName to the name of your Cloud Account.
Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

Set postgres.backup.aws.policyName to the name of the policy created in step 3.

GCS

Create a GCS bucket. Set postgres.backup.gcp.bucket in your values file.
If you do not have a Control Plane Cloud Account set up, follow the Create a Cloud Account guide. Set postgres.backup.gcp.cloudAccountName to the name of your Cloud Account.
Add the Storage Admin role to the GCP service account associated with the Cloud Account.

Installation

To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

The default values.yaml for this template:

resources:
  cpu: 512m
  memory: 1024Mi

firewall:
  external:
    inboundAllowCIDR:
      - 0.0.0.0/0
    outboundAllowCIDR: [] # Set to 0.0.0.0/0 to allow outbound traffic if communicating with an IdP
  internal:
    type: same-gvc # options: same-gvc, same-org, workload-list
    workloads: # Note: can only be used if type is same-gvc or workload-list
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

# Database configuration
postgres:
  image: postgres:18
  config:
    username: username
    password: password
    database: test
  resources:
    minCpu: 200m
    minMemory: 128Mi
    maxCpu: 500m
    maxMemory: 256Mi
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
    autoscaling:
      enabled: false
      maxCapacity: 100 # Maximum capacity in GiB
      minFreePercentage: 10 # Trigger scaling when free space drops below this percentage
      scalingFactor: 1.2 # Multiply current capacity by this factor when scaling up

  internalAccess:
    type: same-gvc # options: none, same-gvc, same-org, workload-list
    workloads: # Note: can only be used if type is same-gvc or workload-list
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

  # Postgres backup configuration (compatible with Postgres 17+)
  backup:
    enabled: false
    image: controlplanecorporation/pg-backup:18.1.0 # tag 18.1.0 = Postgres 18, 17.1.0 = Postgres 17
    schedule: "0 2 * * *" # daily at 2am UTC

    resources:
      cpu: 100m
      memory: 128Mi

    provider: aws # Options: aws or gcp

    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: postgres/backups # Folder path within the bucket

    gcp:
      bucket: my-backup-bucket
      cloudAccountName: my-backup-cloudaccount
      prefix: postgres/backups

FusionAuth Resources

resources.cpu / resources.memory — CPU and memory allocated to the FusionAuth workload.

Firewall

firewall.external.inboundAllowCIDR — CIDR ranges allowed to reach FusionAuth from the internet (default: 0.0.0.0/0).
firewall.external.outboundAllowCIDR — CIDR ranges FusionAuth is allowed to reach externally. Empty by default. Set to 0.0.0.0/0 (or a specific CIDR) if FusionAuth needs to communicate with an external Identity Provider such as Google OAuth.
firewall.internal.type — Controls which internal workloads can reach FusionAuth (same-gvc, same-org, or workload-list).

PostgreSQL

postgres.config.username / postgres.config.password — Database credentials. Change before deploying to production.
postgres.config.database — Name of the database created on startup.

These values are only applied on first startup when the data directory is empty. Updating them after the initial deployment will have no effect on the running database. To change credentials or the database name on an existing instance, use PostgreSQL’s native commands (e.g. ALTER USER, ALTER DATABASE).

postgres.resources — Min/max CPU and memory bounds for the PostgreSQL workload.
postgres.internalAccess.type — Controls which workloads can reach PostgreSQL. Set to none to isolate replicas from each other, or use same-gvc, same-org, or workload-list.

PostgreSQL Storage

postgres.volumeset.capacity — Initial volume size in GiB (minimum 10).
postgres.volumeset.autoscaling.enabled — Automatically expand the volume as it fills. When enabled:
- maxCapacity — Maximum volume size in GiB.
- minFreePercentage — Trigger a scale-up when free space drops below this percentage.
- scalingFactor — Multiply the current capacity by this factor when scaling up.

PostgreSQL Backup

Set postgres.backup.enabled: true to enable scheduled database dumps to object storage. The backup image tag corresponds to the PostgreSQL version (18.1.0 for Postgres 18, 17.1.0 for Postgres 17). Set postgres.backup.provider to aws or gcp and fill in the corresponding section. The prefix field controls the folder path within the bucket where backups are stored.

Restoring a Backup

To restore from a backup, run the following from a client with access to the bucket: AWS S3

export PGPASSWORD="PASSWORD"

aws s3 cp "s3://BUCKET_NAME/PREFIX/BACKUP_FILE.sql.gz" - \
  | gunzip \
  | psql \
      --host=WORKLOAD_NAME \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD

GCS

export PGPASSWORD="PASSWORD"

gsutil cp "gs://BUCKET_NAME/PREFIX/BACKUP_FILE.sql.gz" - \
  | gunzip \
  | psql \
      --host=WORKLOAD_NAME \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD

Post-Deployment Setup

After deployment, open the FusionAuth admin panel to complete setup:

Use the setup wizard to create your application.
Configure your application with the origin, redirect, and logout URLs for your code.
Set the tenant issuer to match your deployment URL (e.g., my-fusionauth-app.io).
If using an external Identity Provider, configure it in the admin panel and ensure firewall.external.outboundAllowCIDR allows traffic to the IdP.

External References

FusionAuth Documentation

Official FusionAuth documentation

OAuth2 & OpenID Connect

FusionAuth OAuth2 and OpenID Connect guide

Cloud Accounts

Create a Control Plane Cloud Account for backup storage access

Backup Image Source

Source code for the PostgreSQL backup container image

FusionAuth Template

View the source files, default values, and chart definition

​Overview

​What Gets Created

​Prerequisites

​AWS S3

​GCS

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​FusionAuth Resources

​Firewall

​PostgreSQL

​PostgreSQL Storage

​PostgreSQL Backup

​Restoring a Backup

​Post-Deployment Setup

​External References

FusionAuth Documentation

OAuth2 & OpenID Connect

Cloud Accounts

Backup Image Source

FusionAuth Template

Overview

What Gets Created

Prerequisites

AWS S3

GCS

Installation

Configuration

FusionAuth Resources

Firewall

PostgreSQL

PostgreSQL Storage

PostgreSQL Backup

Restoring a Backup

Post-Deployment Setup

External References