Importing database & files, and backups

The Drupal Operator has built-in workflows for:

  • Importing database dumps
  • Importing files archives
  • Scheduling automatic backups for DB and files

These are driven by fields in the Drupal custom resource and by Ansible logic in roles/setup/tasks/main.yaml.

Database import

Controlled by:

  • drupal_import_database (boolean)
  • drupal_database_backup_path (string path inside the container/image)
  • change_cause (string, used in checksum)

How it works (high level)

In roles/setup/tasks/main.yaml:

  1. The operator calculates a hash (drupal_db_import_checksum) from:

    • spec.drupal_image
    • spec.drupal_database_backup_path
    • spec.change_cause

  2. If the checksum is new or changed compared to status.lastDbImportChecksum:

    • The Drupal Deployment is scaled down to 0 replicas.
    • A database import Job is created from templates/mariadb-import-job.yml.j2.
    • The operator waits until the Job has status.succeeded > 0.

  3. When the Job succeeds:

    • The operator updates a DatabaseImportStatus custom resource:

      apiVersion: digitalist.cloud/v1alpha1 kind: DatabaseImportStatus metadata: name: "-dbimport" namespace: "" spec: targetDatabase: "-db"

    • The Drupal CR status is updated with:

    • status.dbImported: true
    • status.lastDbImportChecksum
    • status.lastDbImportDate (timestamp)

  4. Drupal is then brought back up and normal reconciliation continues.

Basic example

Example Drupal spec snippet:

spec:
  drupal_import_database: true
  drupal_database_backup_path: "/backups/db.sql"
  change_cause: "initial-import-2025-01-01"

Apply or update your Drupal resource:

kubectl apply -f my-drupal.yaml

The operator will:

  • Scale down the Drupal Deployment
  • Run the DB import Job
  • Wait for completion
  • Record status and scale Drupal back up

Re-importing a database

To trigger a new import (for example, when your dump has changed), you must change something that affects the checksum, typically:

  • drupal_database_backup_path, or
  • change_cause

For example:

spec:
  change_cause: "db-import-2025-02-01"

Then apply the updated CR. A new import Job will be created and tracked.

Files import

Controlled by:

  • drupal_import_files (boolean)
  • drupal_files_backup_path (string path inside the container/image)
  • change_cause (string, used in checksum)

How it works

Similar to the DB import flow:

  1. The operator calculates drupal_files_import_checksum from:

    • spec.drupal_image
    • spec.drupal_files_backup_path
    • spec.change_cause

  2. If the checksum is new/changed:

    • A files import Job is created from templates/files-import-job.yml.j2.

  3. The operator waits until the Job has status.succeeded > 0.

  4. It updates the Drupal CR status:

    • status.filesImported: true
    • status.lastFilesImportChecksum
    • status.lastFilesImportDate

Basic example

spec:
  drupal_import_files: true
  drupal_files_backup_path: "/backups/files.tar.gz"
  change_cause: "files-import-2025-01-01"

After applying the CR, the operator will run a files import Job and track its result in the status fields.

Re-importing files

As with the DB import, change a checksum input (for example change_cause) to trigger a new files import:

spec:
  change_cause: "files-import-2025-02-01"

Apply the updated CR, and a new import Job will be created.

Coordination with cron and deployments

Before running imports or major updates, the operator (see tasks in roles/setup/tasks/main.yaml):

  • Scales down the Drupal Deployment (for DB import).
  • Suspends Drupal CronJob if drupal_cron is enabled.
  • Suspends backup CronJobs if backup_db or backup_files are enabled.
  • Deletes old import Jobs and their Pods.

After the import and after Drupal is ready again, it:

  • Unsuspends the Drupal CronJob.
  • Unsuspends backup CronJobs.

This ensures imports run in a controlled, consistent state.

Automatic backups

The operator can also create CronJobs to perform scheduled backups.

Controlled by:

  • backup_db (boolean)
  • backup_files (boolean)
  • backup_db_cron_schedule
  • backup_files_cron_schedule

Defaults:

  • backup_db: false
  • backup_files: false
  • backup_db_cron_schedule: "0 3 * * *" # daily at 03:00
  • backup_files_cron_schedule: "0 5 * * *" # daily at 05:00

If enabled, the operator creates:

  • DB backup CronJob: <name>-auto-db-backup
  • Files backup CronJob: <name>-auto-files-backup

These CronJobs use templates:

  • templates/automatic-db-backup.yaml.j2
  • templates/automatic-files-backup.yaml.j2

and typically rely on:

  • drupal_backup_secret (default: "backup-secret")
  • drupal_s3_alias, drupal_sla (for S3 or similar backends, depending on your templates)

Example: enable automatic DB backup

spec:
  backup_db: true
  backup_db_cron_schedule: "0 3 * * *"

Example: enable automatic files backup

spec:
  backup_files: true
  backup_files_cron_schedule: "0 5 * * *"

Cleanup and safety notes

  • The operator automatically deletes old Jobs and their Pods before creating new ones (DB import, files import, locale update, backups).
  • Never run make uninstall on a live cluster, as that removes CRDs and triggers deletion of all associated resources (including backups).

For more details on the CronJobs and Jobs involved, see Cron & scheduled tasks.