atscalectl backup

The backup command creates a backup of an AtScale deployment, including the PostgreSQL databases and Kubernetes configuration resources.

AtScale recommends creating a backup before doing any of the following:

• Upgrading AtScale.
• Making changes to the database.
• Making changes to your Keycloak configuration.
• Performing maintenance activities that may affect the deployment.

The backup can be stored locally or uploaded directly to Amazon S3-compatible storage.

Prerequisites

backup requires the following Kubernetes permissions:

• pods get/list
• pods/exec create
• secrets get/list
• configmaps list
• secrets list. Required only when the --release-name flag isn't specified. This is required to detect the Helm release.
• (External PostgreSQL only) pods create/delete. Required to create and delete the temporary utility pod used to back up the external database.
• (External PostgreSQL only) pod/exec. Required in the PostgreSQL namespace if the --pg-namespace flag is specified.

Note

Database tools such as pg_dump run inside the Kubernetes environment, so PostgreSQL client tools are not required on the machine running atscalectl.

Usage

atscalectl backup [flags]

Flags

backup can be used with all global flags, as well as the following command-specific flags.

Flag	Default	Description
--mode	full	The type of backup to perform: full, quick, or secrets-only. For more information, see Backup modes below.
--output-dir	.	The directory where the backup is written.
--databases	atscale,keycloak,pgwire	The databases to dump. Database names must start with a letter or underscore, and can contain only letters, numbers, and underscores. Values are validated before the backup starts.

Backup modes

You can specify the type of backup to perform by running backup with the --mode flag. --mode supports the following values.

Mode	Description
full	Default. Includes global objects, individual database dumps, a complete pg_dumpall, and Kubernetes secrets.
quick	Includes global objects, individual database dumps, and Kubernetes secrets. Does not perform the full dump, making it faster and smaller.
secrets-only	Includes Kubernetes secrets and ConfigMaps only. No database access.

External PostgreSQL flags

If you use an external PostgreSQL database, rather than AtScale's internal database, you can include the following flags to adjust the utility pod that performs the backup. For more information, see External PostgreSQL backups and External PostgreSQL backup examples.

Flag	Description
--pg-host	The external PostgreSQL host.
--pg-port	The external PostgreSQL port. Defaults to 5432.
--pg-connection-string	The full connection URI. Mutually exclusive with --pg-host.
--pg-secret-name	The Kubernetes secret containing PostgreSQL credentials.
--pg-user-key	The username key inside the --pg-secret-name secret. Defaults to POSTGRES_USER.
--pg-password-key	The password key inside the secret. Defaults to POSTGRES_PASSWORD.
--pg-image	The image for the utility pod. Defaults to postgres:16.
--pg-pod-timeout	Determines how long the utility pod stays alive. Defaults to 1h.
--pg-pod	Targets a specific database pod and skips discovery.
--pg-namespace	The namespace of the database pod, if different from AtScale's.

If your cluster enforces pod security policies, image pull secrets, or node placement, you can include the following pod hardening flags to adjust the utility pod. For more information, see External PostgreSQL backups.

Flag	Description
--pg-service-account	ServiceAccount for the utility pod.
--pg-image-pull-secret	Image pull secret name, repeatable.
--pg-node-selector	Node selector as key=value, repeatable.
--pg-pod-label	Extra pod labels as key=value, repeatable.
--pg-pod-annotation	Pod annotations as key=value, repeatable.
--pg-run-as-user	Overrides the default utility pod UID (999).
--pg-run-as-group	Overrides the default utility pod UID (999).
--pg-fs-group	fsGroup GID.

Amazon S3 bucket flags

To configure backup to upload the full database backup to an S3 bucket, you must include the --s3-bucket flag. This flag can be used with the following additional flags. For more information, see Uploading backups to Amazon S3 and Amazon S3 upload examples.

Note

Every --s3-* flag requires --s3-bucket. Validation happens before any dump runs.

Flag	Description
--s3-bucket	Target bucket. Enables uploading to S3. Must be included when using any other --s3-* flag.
--s3-prefix	Key prefix for uploaded objects.
--s3-region	Region. Defaults to Amazon Web Services environment configuration.
--s3-endpoint	Custom endpoint for S3-compatible storage.
--s3-path-style	Path-style addressing, required by some S3-compatible endpoints.
--s3-sse	Server-side encryption. Supported values: aws:kms, AES256
--s3-kms-key-id	KMS key ID or ARN. Requires --s3-sse aws:kms.
--s3-storage-class	Storage class; for example STANDARD_IA or GLACIER. This value must be a valid S3 storage class.
--s3-part-size	Multipart part size in bytes. Uses AWS SDK defaults when not specified.
--s3-concurrency	Multipart upload concurrency. Uses AWS SDK defaults when not specified.
--delete-local	Deletes the local backup directory after a fully successful upload. Only removes the local copy once every object has uploaded successfully. If any upload fails, the local backup is kept.

What a backup contains

Each backup run creates a timestamped directory like the following, so backups never overwrite each other.

Important

These directories contain credentials and database contents in plain text. Protect them with the same security controls as the cluster itself.

atscale-backup-20260727-143000/
  globals.sql            # roles and tablespaces
  atscale.dump           # per-database dumps
  keycloak.dump
  pgwire.dump
  full.sql               # complete pg_dumpall (full mode only)
  secrets/
    all-secrets.yaml     # every Secret in the namespace
    all-configmaps.yaml  # every ConfigMap in the namespace

Internal PostgreSQL backups

If you use AtScale's internal PostgreSQL database, backup runs directly against a PostgreSQL pod. atscalectl prefers a Ready replica pod when available to reduce load on the primary database. If no Ready replica exists, it falls back to the primary database pod.

External PostgreSQL backups

If you use a managed database such as Amazon RDS or Google Cloud SQL instead of AtScale's internal PostgreSQL database, atscalectl uses the Kubernetes API to create a short-lived utility pod inside the Kubernetes cluster. This pod uses a PostgreSQL client image containing pg_dump and related tools and connects to the external database. Once the backup operation completes, the utility pod is deleted by atscalectl.

At a high level, the utility pod has the following attributes.

Utility Pod Attribute	Value
Pod name	atscalectl-pgtools-<timestamp>
Namespace	The AtScale namespace, or --pg-namespace. For more information, see External PostgreSQL flags.
Image	Defaults to postgres:16. You can override this with --pg-image; for more information, see External PostgreSQL flags.
Security context	Runs as UID/GID 999 by default. You can override this with --pg-run-as-user and --pg-run-as-group if needed; for more information, see External PostgreSQL flags.
Container	pgtools
Command	sleep <timeout>
Restart policy	Never
Lifetime	Controlled by --pg-pod-timeout. Defaults to 1h. For more information, see External PostgreSQL flags.

atscalectl waits for the utility pod to reach Running state before executing PostgreSQL commands inside it. If the atscalectl process is interrupted before cleanup, the pod remains until its configured lifetime expires. For long-running backups of large databases, you may need to increase --pg-pod-timeout to ensure the utility pod remains available until the dump completes. For example:

atscalectl backup \
  --pg-host <hostname> \
  --pg-pod-timeout 4h

The utility pod's image must be pullable from the Kubernetes cluster. In restricted or air-gapped environments, you should provide an internal image and image pull secret:

atscalectl backup \
  --pg-image <hostname>/postgres:16 \
  --pg-image-pull-secret <secret_name>

External PostgreSQL credentials

When connecting to a managed PostgreSQL service, credentials are provided to the temporary utility pod during the backup operation. Ensure that Kubernetes RBAC permissions are restricted so only trusted users can inspect pods in namespaces where managed PostgreSQL backups are performed.

Backup limitations with external PostgreSQL databases

Managed PostgreSQL services such as Amazon RDS do not provide PostgreSQL superuser access. Because of this, pg_dumpall cannot read cluster-wide objects from pg_authid. The backup handles this case as non-fatal. The output will show:

skipped: managed PostgreSQL without superuser cannot dump globals — roles and cluster-wide grants must be provisioned separately

Database contents are backed up normally, but roles, passwords, and cluster-wide grants are not included. Restoring into an empty server requires these roles and grants to exist beforehand. Note that this limitation does not affect database-level dumps.

For in-cluster PostgreSQL deployments, where the CLI can access a PostgreSQL superuser, globals.sql is created normally.

Uploading backups to Amazon S3

You can optionally configure backup to upload the full database backup to an Amazon S3 bucket after the local dump finishes. To do so, you must include the --s3-bucket flag. For more information, see Amazon S3 bucket flags and Amazon S3 upload examples.

When uploading backups to Amazon S3, credentials come from the standard AWS credential chain:

• IRSA when running in AWS infrastructure.
• Environment variables or AWS profiles when running locally.

Note

AWS credentials are never passed as command-line arguments.

Scheduling backups

You can run backup as a Kubernetes CronJob using the published container image, with IRSA supplying S3 credentials. For example:

atscalectl backup \
  --mode quick \
  --s3-bucket <bucket> \
  --s3-prefix <prefix> \
  --delete-local

Note

With --delete-local, the job needs only temporary scratch space.

Backup verification

Each dump is verified as it is written. A dump that is silently truncated (for example, because the connection to the database pod dropped during transfer) is reported as a failure instead of a successful backup. Check the NOTES column in the output for files that did not complete cleanly.

Backup failure handling

The backup fails if the database dump fails and exits with code 1. If either the globals.sql or full.sql file fails, the backup continues and reports a non-fatal note.

Backup usage examples

Full backup before an upgrade

atscalectl backup \
  --mode full \
  --output-dir <dir>

Faster backup to a specific location

atscalectl backup \
  --mode quick \
  --output-dir <dir>

Backup a single database

atscalectl backup \
  --databases keycloak

Backup configuration only

atscalectl backup \
  --mode secrets-only

External PostgreSQL backup examples

Specify a host and secret

atscalectl backup \
  --pg-host <hostname> \
  --pg-secret-name <secret_name>

Specify the full connection URI

atscalectl backup \
  --pg-connection-string "postgresql://<user>:<password>@<host>:5432/postgres"

Use a custom PostgreSQL image

atscalectl backup \
  --pg-host <hostname> \
  --pg-image <host>/postgres:16

Amazon S3 upload examples

Basic upload

atscalectl backup \
  --s3-bucket <bucket> \
  --s3-prefix <prefix>

Upload encrypted with KMS, local copy removed afterwards

atscalectl backup \
  --s3-bucket <bucket> \
  --s3-sse aws:kms \
  --s3-kms-key-id <key-arn> \
  --delete-local

Upload to S3-compatible storage

atscalectl backup \
  --s3-bucket <bucket> \
  --s3-endpoint <endpoint> \
  --s3-path-style

Troubleshooting backups

Invalid backup mode

If you receive an invalid mode error:

invalid --mode

Rerun backup with a valid --mode value: full, quick, or secrets-only.

Mutually exclusive flags

If you receive an error stating the specified flags are mutually exclusive:

--pg-host and --pg-connection-string are mutually exclusive

Re-run backup with only one of the flags.

Missing S3 target bucket

If you receive an error like the following:

--s3-prefix requires --s3-bucket

Rerun the command and specify the --s3-bucket flag. All S3 flags require a target bucket.

The globals.sql file is skipped

The external PostgreSQL instance does not provide superuser access. Roles and cluster-wide grants must be provisioned separately. For more information, see the Backup limitations with external PostgreSQL databases section above.

Backup stops with a database dump error

The affected database was not backed up. Fix the database connection or permissions issue and run the backup again.

Kubernetes access denied

If you are backing up an external PostgreSQL instance, verify your permissions:

kubectl auth can-i create pods -n <namespace>
kubectl auth can-i delete pods -n <namespace>
kubectl auth can-i create pods/exec -n <namespace>