# debjotimallick/kube-db-backup architecture

> Architecture diagram of the GitHub repository debjotimallick/kube-db-backup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/debjotimallick/kube-db-backup
- Repository: https://github.com/debjotimallick/kube-db-backup

## Overview

kube-db-backup is a Kubernetes operator for database backup and restore. Users define connection and storage configuration, then request a one-shot or scheduled backup, or a restore from a Backup or raw S3 path. Reconcilers resolve engine metadata and create Jobs; engine containers perform database-specific work and communicate results through a shared contract, after which the operator updates resource status and retries eligible failures. The schedule reconciler also creates Backup resources and prunes history. Relationships for unsampled engine and storage behavior follow the README; implementation detail is limited to the excerpts provided.

Main entry points: [`internal/controller/backup_controller.go`](https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/backup_controller.go) (Backup reconciler), [`internal/controller/restore_controller.go`](https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/restore_controller.go) (Restore reconciler), [`engines/postgres/entrypoint.sh`](https://github.com/debjotimallick/kube-db-backup/blob/main/engines/postgres/entrypoint.sh) (Engine container), [`cmd/main.go`](https://github.com/debjotimallick/kube-db-backup/blob/main/cmd/main.go) (Controller manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Kubernetes resources"]
  node_dbinstance["Database instance"]
  node_backupconfig["Backup configuration"]
  node_backup["Backup request<br/>[backup_types.go]"]
  node_schedule["Backup schedule"]
  node_restore["Restore request<br/>[restore_types.go]"]
end

subgraph group_control["Operator control plane"]
  node_manager["Controller manager<br/>[main.go]"]
  node_schedulectrl["Schedule reconciler"]
  node_backupctrl["Backup reconciler"]
  node_restorectrl["Restore reconciler"]
  node_helpers["Status helpers<br/>[helpers.go]"]
end

subgraph group_execution["Job execution"]
  node_registry["Engine registry<br/>[registry.go]"]
  node_contract["Engine contract<br/>[contract.go]"]
  node_job["Kubernetes Job"]
  node_enginecontainer["Engine container<br/>[entrypoint.sh]"]
end

subgraph group_integrations["External systems"]
  node_db[("Database")]
  node_objectstore[("S3-compatible storage")]
  node_secret[("Kubernetes Secrets")]
  node_k8s["Kubernetes API"]
end

node_user(("Operator user"))

node_user -->|"configures"| node_dbinstance
node_user -->|"configures"| node_backupconfig
node_user -->|"requests"| node_backup
node_user -->|"schedules"| node_schedule
node_user -->|"requests"| node_restore
node_manager -->|"registers"| node_backupctrl
node_manager -->|"registers"| node_schedulectrl
node_manager -->|"registers"| node_restorectrl
node_schedulectrl -->|"creates"| node_backup
node_schedulectrl -->|"updates status"| node_schedule
node_backupctrl -->|"reads config"| node_dbinstance
node_backupctrl -->|"reads config"| node_backupconfig
node_backupctrl -->|"looks up engine"| node_registry
node_backupctrl -->|"creates"| node_job
node_backupctrl -->|"uses result contract"| node_contract
node_backupctrl -->|"updates status"| node_backup
node_restorectrl -->|"reads target"| node_dbinstance
node_restorectrl -->|"reads config"| node_backupconfig
node_restorectrl -->|"reads source"| node_backup
node_restorectrl -->|"looks up engine"| node_registry
node_restorectrl -->|"creates"| node_job
node_restorectrl -->|"updates status"| node_restore
node_backupctrl -->|"sets conditions"| node_helpers
node_restorectrl -.->|"sets conditions"| node_helpers
node_job -->|"runs"| node_enginecontainer
node_registry -->|"selects image"| node_enginecontainer
node_enginecontainer -->|"emits result"| node_contract
node_enginecontainer -->|"dumps or restores"| node_db
node_enginecontainer -->|"uploads or reads"| node_objectstore
node_job -->|"mounts credentials"| node_secret
node_manager -->|"runs controllers"| node_k8s
node_backupctrl -->|"observes Job"| node_k8s
node_restorectrl -->|"observes Job"| node_k8s

click node_dbinstance "https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/databaseinstance_types.go"
click node_backupconfig "https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/backupconfig_types.go"
click node_backup "https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/backup_types.go"
click node_schedule "https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/backupschedule_types.go"
click node_restore "https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/restore_types.go"
click node_manager "https://github.com/debjotimallick/kube-db-backup/blob/main/cmd/main.go"
click node_schedulectrl "https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/backupschedule_controller.go"
click node_backupctrl "https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/backup_controller.go"
click node_restorectrl "https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/restore_controller.go"
click node_helpers "https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/helpers.go"
click node_registry "https://github.com/debjotimallick/kube-db-backup/blob/main/pkg/engine/registry.go"
click node_contract "https://github.com/debjotimallick/kube-db-backup/blob/main/pkg/engine/contract.go"
click node_enginecontainer "https://github.com/debjotimallick/kube-db-backup/blob/main/engines/postgres/entrypoint.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dbinstance,node_backupconfig,node_backup,node_schedule,node_restore,node_user toneBlue
class node_manager,node_schedulectrl,node_backupctrl,node_restorectrl,node_helpers toneAmber
class node_registry,node_contract,node_job,node_enginecontainer toneMint
class node_db,node_objectstore,node_secret,node_k8s toneRose
```

## Components

### Kubernetes resources

- [Database instance](https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/databaseinstance_types.go): `api/v1alpha1/databaseinstance_types.go`
- [Backup configuration](https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/backupconfig_types.go): `api/v1alpha1/backupconfig_types.go`
- [Backup request](https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/backup_types.go): `api/v1alpha1/backup_types.go`
- [Backup schedule](https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/backupschedule_types.go): `api/v1alpha1/backupschedule_types.go`
- [Restore request](https://github.com/debjotimallick/kube-db-backup/blob/main/api/v1alpha1/restore_types.go): `api/v1alpha1/restore_types.go`

### Operator control plane

- [Controller manager](https://github.com/debjotimallick/kube-db-backup/blob/main/cmd/main.go): `cmd/main.go`
- [Schedule reconciler](https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/backupschedule_controller.go): `internal/controller/backupschedule_controller.go`
- [Backup reconciler](https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/backup_controller.go): `internal/controller/backup_controller.go`
- [Restore reconciler](https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/restore_controller.go): `internal/controller/restore_controller.go`
- [Status helpers](https://github.com/debjotimallick/kube-db-backup/blob/main/internal/controller/helpers.go): `internal/controller/helpers.go`

### Job execution

- [Engine registry](https://github.com/debjotimallick/kube-db-backup/blob/main/pkg/engine/registry.go): `pkg/engine/registry.go`
- [Engine contract](https://github.com/debjotimallick/kube-db-backup/blob/main/pkg/engine/contract.go): `pkg/engine/contract.go`
- **Kubernetes Job**
- [Engine container](https://github.com/debjotimallick/kube-db-backup/blob/main/engines/postgres/entrypoint.sh): `engines/postgres/entrypoint.sh`

### External systems

- **Database**
- **S3-compatible storage**
- **Kubernetes Secrets**
- **Kubernetes API**

### Other components

- **Operator user**

## Connections

- Operator user → Database instance: configures (evidence: `README.md`)
- Operator user → Backup configuration: configures (evidence: `README.md`)
- Operator user → Backup request: requests (evidence: `README.md`)
- Operator user → Backup schedule: schedules (evidence: `README.md`)
- Operator user → Restore request: requests (evidence: `README.md`)
- Controller manager → Backup reconciler: registers (evidence: `cmd/main.go`)
- Controller manager → Schedule reconciler: registers (evidence: `cmd/main.go`)
- Controller manager → Restore reconciler: registers (evidence: `cmd/main.go`)
- Schedule reconciler → Backup request: creates (evidence: `internal/controller/backupschedule_controller.go`)
- Schedule reconciler → Backup schedule: updates status (evidence: `internal/controller/backupschedule_controller.go`)
- Backup reconciler → Database instance: reads config (evidence: `internal/controller/backup_controller.go`)
- Backup reconciler → Backup configuration: reads config (evidence: `internal/controller/backup_controller.go`)
- Backup reconciler → Engine registry: looks up engine (evidence: `internal/controller/backup_controller.go`)
- Backup reconciler → Kubernetes Job: creates (evidence: `internal/controller/backup_controller.go`)
- Backup reconciler → Engine contract: uses result contract (evidence: `README.md`)
- Backup reconciler → Backup request: updates status (evidence: `internal/controller/backup_controller.go`)
- Restore reconciler → Database instance: reads target (evidence: `internal/controller/restore_controller.go`)
- Restore reconciler → Backup configuration: reads config (evidence: `internal/controller/restore_controller.go`)
- Restore reconciler → Backup request: reads source (evidence: `internal/controller/restore_controller.go`)
- Restore reconciler → Engine registry: looks up engine (evidence: `internal/controller/restore_controller.go`)
- Restore reconciler → Kubernetes Job: creates (evidence: `internal/controller/restore_controller.go`)
- Restore reconciler → Restore request: updates status (evidence: `internal/controller/restore_controller.go`)
- Backup reconciler → Status helpers: sets conditions (evidence: `internal/controller/backup_controller.go`)
- Restore reconciler → Status helpers: sets conditions
- Kubernetes Job → Engine container: runs (evidence: `README.md`)
- Engine registry → Engine container: selects image (evidence: `README.md`)
- Engine container → Engine contract: emits result (evidence: `README.md`)
- Engine container → Database: dumps or restores (evidence: `README.md`)
- Engine container → S3-compatible storage: uploads or reads (evidence: `README.md`)
- Kubernetes Job → Kubernetes Secrets: mounts credentials (evidence: `README.md`)
- Controller manager → Kubernetes API: runs controllers (evidence: `README.md`)
- Backup reconciler → Kubernetes API: observes Job (evidence: `README.md`)
- Restore reconciler → Kubernetes API: observes Job (evidence: `README.md`)