Zum Hauptinhalt springen
Version: 3.0.0-alpha (Diátaxis)

API-Referenz PostgreSQL

Diese Referenz beschreibt die Verwendung von PostgreSQL auf Hikube, mit Schwerpunkt auf dem Betrieb als replizierter Cluster mit einem Primary und Standbys für Hochverfügbarkeit sowie der Möglichkeit, automatische Sicherungen auf S3-kompatiblen Speicher zu aktivieren.

Grundstruktur​

Postgres-Ressource​

YAML-Konfigurationsbeispiel​

apiVersion: apps.cozystack.io/v1alpha1
kind: Postgres
metadata:
  name: example
spec:

Parameter​

Allgemeine Parameter​

ParameterTypBeschreibungStandardErforderlich
replicasintAnzahl der PostgreSQL-Replikas (Instanzen im Cluster)2Ja
resourcesobjectExplizite CPU- und Speicherkonfiguration für jedes PostgreSQL-Replika. Wenn leer, wird resourcesPreset angewendet{}Nein
resources.cpuquantityVerfügbare CPU pro ReplikanullNein
resources.memoryquantityVerfügbarer Speicher (RAM) pro ReplikanullNein
resourcesPresetstringStandard-Dimensionierungsprofil (nano, micro, small, medium, large, xlarge, 2xlarge)"micro"Ja
sizequantityPersistent Volume Claim-Größe für Anwendungsdaten10GiJa
storageClassstringStorageClass zur Datenspeicherung""Nein
externalboolExternen Zugriff von außerhalb des Clusters aktivierenfalseNein

YAML-Konfigurationsbeispiel​

postgresql.yaml
apiVersion: apps.cozystack.io/v1alpha1
kind: Postgres
metadata:
  name: postgres-example
spec:
  # Anzahl der PostgreSQL-Replikas (Instanzen im Cluster)
  replicas: 3
  # Explizite Ressourcenkonfiguration
  resources:
    cpu: 2000m     # 2 vCPU pro Instanz
    memory: 2Gi    # 2 GiB RAM pro Instanz
  # Verwendung eines Presets wenn resources leer ist
  resourcesPreset: micro
  # Persistentes Volume für jede PostgreSQL-Instanz
  size: 10Gi
  # Speicherklasse (leer lassen für die Standard-Klasse des Clusters)
  storageClass: "replicated"
  # Datenbank extern freigeben (LoadBalancer wenn true)
  external: false

Anwendungsspezifische Parameter​

ParameterTypBeschreibungStandardErforderlich
postgresqlobjectPostgreSQL-Serverkonfiguration{}Nein
postgresql.parametersobjectPostgreSQL-Serverparameter{}Nein
postgresql.parameters.max_connectionsintMaximale Anzahl gleichzeitiger Verbindungen zum Datenbankserver (Standard: 100)100Nein
quorumobjectQuorum-Konfiguration für synchrone Replikation{}Nein
quorum.minSyncReplicasintMindestanzahl synchroner Replikas, die eine Transaktion bestätigen müssen0Nein
quorum.maxSyncReplicasintMaximale Anzahl synchroner Replikas, die eine Transaktion bestätigen können0Nein
usersmap[string]objectBenutzerkonfiguration{...}Nein
users[name].passwordstringPasswort des BenutzersnullJa
users[name].replicationboolOb der Benutzer Replikationsrechte hatnullNein
databasesmap[string]objectDatenbankkonfiguration{...}Nein
databases[name].rolesobjectRollen für die DatenbanknullNein
databases[name].roles.admin[]stringListe der Benutzer mit Admin-Rechten[]Nein
databases[name].roles.readonly[]stringListe der Benutzer mit Leserechten[]Nein
databases[name].extensions[]stringAktivierte Erweiterungen für die Datenbank[]Nein

YAML-Konfigurationsbeispiel​

postgresql.yaml
spec:
  replicas: 3
  size: 10Gi
  storageClass: replicated
  resourcesPreset: medium

  # PostgreSQL-Serverkonfiguration
  postgresql:
    parameters:
      max_connections: 200
      shared_buffers: 512MB
      work_mem: 64MB

  # Quorum-Konfiguration für synchrone Replikation
  quorum:
    minSyncReplicas: 1
    maxSyncReplicas: 2

  # Benutzer
  users:
    admin:
      password: StrongAdminPwd123
      replication: true
    appuser:
      password: AppUserPwd456
    readonly:
      password: ReadOnlyPwd789

  # Datenbanken
  databases:
    myapp:
      roles:
        admin:
          - admin
        readonly:
          - readonly
      extensions:
        - hstore
        - uuid-ossp

    analytics:
      roles:
        admin:
          - admin
        readonly:
          - appuser
      extensions:
        - pgcrypto

Backup-Parameter​

ParameterTypBeschreibungStandardErforderlich
backupobjectBackup-Konfiguration{}Nein
backup.enabledboolRegelmäßige Sicherungen aktivierenfalseNein
backup.schedulestringCron-Zeitplan für automatische Sicherungen"0 2 * * * *"Nein
backup.retentionPolicystringAufbewahrungsrichtlinie"30d"Nein
backup.destinationPathstringSpeicherpfad für die Sicherung (z.B. s3://bucket/path/)"s3://bucket/path/to/folder/"Ja
backup.endpointURLstringS3-Endpoint zum Hochladen der Daten"https://prod.s3.hikube.cloud"Ja
backup.s3AccessKeystringZugriffsschlüssel für S3 zur Authentifizierung<your-access-key>Ja
backup.s3SecretKeystringGeheimer Schlüssel für S3 zur Authentifizierung<your-secret-key>Ja

Um eine PostgreSQL-Datenbank zu sichern, ist ein externer S3-kompatibler Speicher erforderlich.

Um regelmäßige Sicherungen zu aktivieren:

  1. Aktualisieren Sie die Konfiguration Ihrer PostgreSQL-Anwendung.
  2. Setzen Sie den Parameter backup.enabled auf true.
  3. Geben Sie den Zielpfad und die Anmeldedaten in den backup.*-Feldern an.

YAML-Konfigurationsbeispiel​

postgresql.yaml
## @param backup.enabled Enable regular backups
## @param backup.schedule Cron schedule for automated backups
## @param backup.retentionPolicy Retention policy
## @param backup.destinationPath Path to store the backup (i.e. s3://bucket/path/to/folder)
## @param backup.endpointURL S3 Endpoint used to upload data to the cloud
## @param backup.s3AccessKey Access key for S3, used for authentication
## @param backup.s3SecretKey Secret key for S3, used for authentication
backup:
  enabled: false
  retentionPolicy: 30d
  destinationPath: s3://bucket/path/to/folder/
  endpointURL: https://prod.s3.hikube.cloud
  schedule: "0 2 * * * *"
  s3AccessKey: oobaiRus9pah8PhohL1ThaeTa4UVa7gu
  s3SecretKey: ju3eum4dekeich9ahM1te8waeGai0oog

Parameter zur Backup-Wiederherstellung​

ParameterTypBeschreibungStandardErforderlich
bootstrapobjectBootstrap-Konfiguration{}Nein
bootstrap.enabledboolDatenbankcluster aus einem Backup wiederherstellenfalseNein
bootstrap.recoveryTimestringZeitstempel (PITR), bis zu dem die Wiederherstellung erfolgen soll (Format RFC 3339). Leer = letztes Backup""Nein
bootstrap.oldNamestringName des PostgreSQL-Clusters vor der Löschung""Ja

Hikube unterstützt die Wiederherstellung zu einem bestimmten Zeitpunkt (Point-In-Time Recovery - PITR). Die Wiederherstellung erfolgt durch Erstellen einer neuen PostgreSQL-Instanz mit einem anderen Namen, aber einer identischen Konfiguration wie die Ursprungsinstanz.

Schritte​

  1. Erstellen Sie eine neue PostgreSQL-Anwendung.
  2. Geben Sie ihr einen anderen Namen als die Ursprungsinstanz.
  3. Aktivieren Sie den Parameter bootstrap.enabled.
  4. Geben Sie an:
    • bootstrap.oldName: den Namen der alten PostgreSQL-Instanz.
    • bootstrap.recoveryTime: den Zeitpunkt, bis zu dem wiederhergestellt werden soll, im Format RFC 3339. Wenn leer gelassen, wird bis zum letzten verfügbaren Zustand wiederhergestellt.

YAML-Konfigurationsbeispiel​

postgresql.yaml
bootstrap:
  enabled: true
  oldName: "postgres-example"   # Name der alten Instanz
  recoveryTime: "2025-01-15T10:30:00Z"  # Wiederherstellung zu einem bestimmten Zeitpunkt (RFC 3339)

resources und resourcesPreset​

Das Feld resources ermöglicht die explizite Definition der CPU- und Speicherkonfiguration jedes PostgreSQL-Replikas. Wenn dieses Feld leer gelassen wird, wird der Wert des Parameters resourcesPreset verwendet.

YAML-Konfigurationsbeispiel​

postgresql.yaml
resources:
  cpu: 4000m
  memory: 4Gi

⚠️ Achtung: Wenn resources definiert ist, wird der Wert von resourcesPreset ignoriert.

Preset-NameCPUSpeicher
nano250m128Mi
micro500m256Mi
small1512Mi
medium11Gi
large22Gi
xlarge44Gi
2xlarge88Gi

Vollständige Beispiele​

Produktionscluster​

postgresql-production.yaml
apiVersion: apps.cozystack.io/v1alpha1
kind: Postgres
metadata:
  name: production
spec:
  replicas: 3
  resources:
    cpu: 4000m
    memory: 8Gi
  size: 50Gi
  storageClass: replicated
  external: false

  postgresql:
    parameters:
      max_connections: 300
      shared_buffers: 2GB
      work_mem: 64MB
      effective_cache_size: 6GB

  quorum:
    minSyncReplicas: 1
    maxSyncReplicas: 2

  users:
    admin:
      password: SecureAdminPassword
      replication: true
    appuser:
      password: SecureAppPassword
    readonly:
      password: SecureReadOnlyPassword

  databases:
    production:
      roles:
        admin:
          - admin
        readonly:
          - readonly
          - appuser
      extensions:
        - uuid-ossp
        - pgcrypto

  backup:
    enabled: true
    schedule: "0 2 * * *"
    retentionPolicy: 30d
    destinationPath: s3://backups/postgresql/production/
    endpointURL: https://prod.s3.hikube.cloud
    s3AccessKey: your-access-key
    s3SecretKey: your-secret-key

Entwicklungscluster​

postgresql-development.yaml
apiVersion: apps.cozystack.io/v1alpha1
kind: Postgres
metadata:
  name: development
spec:
  replicas: 1
  resourcesPreset: nano
  size: 5Gi
  external: true

  users:
    dev:
      password: devpassword

  databases:
    devdb:
      roles:
        admin:
          - dev
Bewährte Praktiken
  • Synchrone Replikation: Konfigurieren Sie quorum.minSyncReplicas: 1 in der Produktion, um sicherzustellen, dass mindestens ein Replika jede Transaktion bestätigt
  • S3-Sicherungen: Aktivieren Sie automatische Sicherungen mit backup.enabled: true und testen Sie regelmäßig die Wiederherstellung
  • Rollentrennung: Erstellen Sie separate Benutzer für Administration, Anwendung und Lesezugriff
  • PostgreSQL-Parameter: Passen Sie shared_buffers (~25% des RAM), work_mem und max_connections an Ihre Arbeitslast an
Achtung
  • Löschungen sind unwiderruflich: Das Löschen einer Postgres-Ressource führt zum endgültigen Datenverlust, wenn keine Sicherung konfiguriert ist
  • resources vs resourcesPreset: Wenn resources definiert ist, wird resourcesPreset vollständig ignoriert
  • PITR-Wiederherstellung: Die Wiederherstellung erstellt eine neue Instanz mit einem anderen Namen — sie stellt nicht die bestehende Instanz wieder her