Vai al contenuto principale
Versione: 3.0.0-alpha (Diátaxis)

Riferimento API MySQL

Questo riferimento descrive in dettaglio l'utilizzo di MySQL su Hikube, evidenziando il deployment in cluster replicato con un primary e delle repliche per l'alta disponibilità, nonche la possibilità di attivare backup automatici verso uno storage compatibile S3.

Struttura di Base​

Risorsa MySQL​

Esempio di configurazione YAML​

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

Parametri​

Parametri Comuni​

ParametroTipoDescrizionePredefinitoRichiesto
replicasintNumero di repliche MariaDB nel cluster2Si
resourcesobjectConfigurazione esplicita CPU e memoria per ogni replica. Se vuoto, viene applicato resourcesPreset{}No
resources.cpuquantityCPU disponibile per ogni replicanullNo
resources.memoryquantityMemoria (RAM) disponibile per ogni replicanullNo
resourcesPresetstringProfilo di risorse predefinito (nano, micro, small, medium, large, xlarge, 2xlarge)nanoSi
sizequantityDimensione del volume persistente (PVC) per archiviare i dati10GiSi
storageClassstringStorageClass utilizzata per archiviare i dati""No
externalboolAttivare un accesso esterno al cluster (LoadBalancer)falseNo

Esempio di configurazione YAML​

mysql.yaml
apiVersion: apps.cozystack.io/v1alpha1
kind: MySQL
metadata:
  name: example              # Nome dell'istanza
spec:
  replicas: 3                # Numero di repliche (1 primary + 2 repliche)

  resources:
    cpu: 1000m               # CPU per replica
    memory: 1Gi              # RAM per replica

  resourcesPreset: nano      # Profilo predefinito se resources e vuoto
  size: 10Gi                 # Dimensione del volume persistente
  storageClass: ""           # Classe di archiviazione
  external: false            # Accesso esterno (LoadBalancer)

Parametri specifici dell'applicazione​

ParametroTipoDescrizionePredefinitoRichiesto
usersmap[string]objectConfigurazione degli utenti{...}Si
users[name].passwordstringPassword dell'utente""Si
users[name].maxUserConnectionsintNumero massimo di connessioni per l'utente0No
databasesmap[string]objectConfigurazione dei database{...}Si
databases[name].rolesobjectRuoli associati al databasenullNo
databases[name].roles.admin[]stringLista degli utenti con diritti admin[]No
databases[name].roles.readonly[]stringLista degli utenti con diritti in lettura[]No

Esempio di configurazione YAML​

mysql.yaml
apiVersion: apps.cozystack.io/v1alpha1
kind: MySQL
metadata:
  name: example
spec:
  replicas: 2
  size: 10Gi
  resourcesPreset: nano
  # Definizione degli utenti MySQL
  users:
    appuser:
      password: strongpassword     # Password dell'utente applicativo
      maxUserConnections: 50       # Limite di connessioni simultanee
    readonly:
      password: readonlypass       # Utente con diritti limitati
      maxUserConnections: 10

  # Definizione dei database
  databases:
    myapp:
      roles:
        admin:
          - appuser                # appuser = admin del database "myapp"
        readonly:
          - readonly               # readonly = accesso in sola lettura
    analytics:
      roles:
        admin:
          - appuser                # appuser = admin del database "analytics"

Parametri di backup​

ParametroTipoDescrizionePredefinitoRichiesto
backupobjectConfigurazione dei backup{}No
backup.enabledboolAttivare i backup regolarifalseNo
backup.s3RegionstringRegione AWS S3 dove sono archiviati i backup"us-east-1"Si
backup.s3BucketstringBucket S3 utilizzato per archiviare i backup"s3.example.org/mysql-backups"Si
backup.schedulestringPianificazione dei backup (cron)"0 2 * * *"No
backup.cleanupStrategystringStrategia di retention per pulire i vecchi backup"--keep-last=3 --keep-daily=3 --keep-within-weekly=1m"No
backup.s3AccessKeystringChiave di accesso S3 (autenticazione)"<your-access-key>"Si
backup.s3SecretKeystringChiave segreta S3 (autenticazione)"<your-secret-key>"Si
backup.resticPasswordstringPassword utilizzata per la cifratura Restic"<password>"Si

Esempio di configurazione YAML​

mysql.yaml
apiVersion: apps.cozystack.io/v1alpha1
kind: MySQL
metadata:
  name: example
spec:
  replicas: 2
  size: 10Gi
  resourcesPreset: small

  # Configurazione dei backup automatici
  backup:
    enabled: true
    s3Region: eu-central-1
    s3Bucket: s3.hikube.cloud/mysql-backups
    schedule: "0 3 * * *"                       # Backup ogni giorno alle 3 del mattino
    cleanupStrategy: "--keep-last=7 --keep-daily=7 --keep-weekly=4"
    s3AccessKey: "HIKUBE123ACCESSKEY"
    s3SecretKey: "HIKUBE456SECRETKEY"
    resticPassword: "SuperStrongResticPassword!"

resources e resourcesPreset​

Il campo resources permette di definire esplicitamente la configurazione CPU e memoria di ogni replica MySQL. Se questo campo e lasciato vuoto, viene utilizzato il valore del parametro resourcesPreset.

Esempio di configurazione YAML​

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

⚠️ Attenzione: se resources e definito, il valore di resourcesPreset viene ignorato.

Preset nameCPUMemoria
nano250m128Mi
micro500m256Mi
small1512Mi
medium11Gi
large22Gi
xlarge44Gi
2xlarge88Gi

Guide pratiche​

Per le procedure dettagliate, consultate le guide dedicate:

Problemi noti​

  • La replica può fallire con diversi errori
  • La replica può fallire se il binlog è stato eliminato. Finche mariadbbackup non viene utilizzato per inizializzare un nodo da mariadb-operator (questa funzionalità non è ancora implementata), seguite questi passaggi manuali per correggere il problema: https://github.com/mariadb-operator/mariadb-operator/issues/141#issuecomment-1804760231
  • Gli indici possono talvolta essere corrotti sulla replica primaria. Potete ripristinarli da una replica secondaria
mysqldump -h <slave> -P 3306 -u<user> -p<password> --column-statistics=0 <database> <table> ~/tmp/fix-table.sql
mysql -h <master> -P 3306 -u<user> -p<password> <database> < ~/tmp/fix-table.sql

Esempi Completi​

Cluster di Produzione​

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

  users:
    admin:
      password: SecureAdminPassword
      maxUserConnections: 100
    appuser:
      password: SecureAppPassword
      maxUserConnections: 500
    readonly:
      password: SecureReadOnlyPassword
      maxUserConnections: 50

  databases:
    production:
      roles:
        admin:
          - admin
        readonly:
          - readonly
    analytics:
      roles:
        admin:
          - admin
        readonly:
          - appuser

  backup:
    enabled: true
    schedule: "0 3 * * *"
    cleanupStrategy: "--keep-last=7 --keep-daily=7 --keep-weekly=4"
    s3Region: eu-central-1
    s3Bucket: s3.hikube.cloud/mysql-backups
    s3AccessKey: your-access-key
    s3SecretKey: your-secret-key
    resticPassword: SecureResticPassword

Cluster di Sviluppo​

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

  users:
    dev:
      password: devpassword
      maxUserConnections: 100

  databases:
    devdb:
      roles:
        admin:
          - dev
Buone Pratiche
  • 3 repliche minimo in produzione per assicurare l'alta disponibilità (1 primary + 2 repliche)
  • maxUserConnections: limitate le connessioni per utente per evitare l'esaurimento delle risorse
  • Backup Restic: attivate i backup automatici con backup.enabled: true e conservate il resticPassword in un luogo sicuro
  • Separazione dei database: create un database per applicazione con ruoli distinti (admin, readonly)
Attenzione
  • Le cancellazioni sono irreversibili: la cancellazione di una risorsa MySQL comporta la perdita definitiva dei dati se nessun backup è configurato
  • Commutazione del primary: il cambio di primary tramite spec.replication.primary.podIndex può comportare una breve interruzione delle scritture
  • Indici corrotti: gli indici possono talvolta essere corrotti sulla replica primaria — ripristinateli da una replica secondaria con mysqldump