Certctl e Docker Compose: Gestione Semplice di Certificati TLS Self-Hosted

La gestione dei certificati TLS è cruciale per proteggere le comunicazioni tra servizi, ma può diventare complessa, specialmente in ambienti di sviluppo e test. I certificati self-signed sono una soluzione rapida, ma richiedono comunque un processo di creazione e rinnovo. certctl semplifica questo processo, automatizzando la generazione e la gestione dei certificati. Combinato con Docker Compose, possiamo creare un ambiente self-hosted completo per la gestione dei certificati TLS, ideale per lo sviluppo e il testing di applicazioni che richiedono comunicazioni sicure. Questo tutorial ti guiderà attraverso la configurazione di un ambiente del genere, permettendoti di generare e rinnovare certificati TLS in modo efficiente e automatizzato.

Prerequisiti

• Docker installato
• Docker Compose installato
• certctl installato (assicurati di avere la versione più recente disponibile)
• Un editor di testo (es. nano, vim)
• Conoscenza base di Docker e Docker Compose

Configurazione di Docker Compose

Creiamo innanzitutto un file docker-compose.yml per definire i servizi necessari. Avremo bisogno di un container per certctl e, opzionalmente, di un container per un servizio di test (come un semplice server web Nginx) per verificare i certificati generati.

version: '3.8'
services:
  certctl:
    image: ghcr.io/cloudflare/certctl:latest
    container_name: certctl
    volumes:
      - ./certs:/certs
    environment:
      - CERTCTL_CA_CN=MySelfSignedCA
    command: sleep infinity # Mantiene il container attivo

  nginx:
    image: nginx:latest
    container_name: nginx-test
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - certctl

Questo file definisce due servizi:

• certctl: Utilizza l’immagine Docker ufficiale di certctl da GitHub Container Registry. Mappa la directory locale ./certs all’interno del container come /certs. Imposta la variabile d’ambiente CERTCTL_CA_CN per definire il Common Name (CN) dell’autorità di certificazione (CA). Il comando sleep infinity mantiene il container in esecuzione, permettendoci di eseguire comandi certctl al suo interno.
• nginx: Utilizza l’immagine Docker di Nginx. Mappa la porta 443 dell’host alla porta 443 del container. Mappa il file di configurazione Nginx locale ./nginx.conf e la directory dei certificati ./certs all’interno del container. depends_on assicura che il container certctl sia avviato prima di nginx.

Creazione della directory dei certificati

Crea una directory locale chiamata certs che verrà utilizzata per memorizzare i certificati generati.

mkdir certs

Creazione del file di configurazione Nginx (opzionale)

Se desideri testare i certificati con Nginx, crea un file nginx.conf con la seguente configurazione:

events {}

http {
    server {
        listen 443 ssl;
        server_name localhost;

        ssl_certificate /etc/nginx/certs/example.com.crt;
        ssl_certificate_key /etc/nginx/certs/example.com.key;

        location / {
            root /usr/share/nginx/html;
            index index.html;
        }
    }
}

Questo file configura Nginx per ascoltare sulla porta 443 (HTTPS) e utilizzare i certificati TLS generati da certctl. Assicurati che i percorsi ssl_certificate e ssl_certificate_key corrispondano ai nomi dei file che verranno generati da certctl.

Generazione della Certificate Authority (CA)

Avvia i container definiti nel file docker-compose.yml:

docker-compose up -d

Questo comando avvierà i container certctl e nginx in background. Ora, eseguiamo il comando certctl ca all’interno del container certctl per generare la CA:

docker exec -it certctl certctl ca

Questo comando genera una nuova CA nella directory /certs all’interno del container certctl. I file ca.crt e ca.key (certificato e chiave privata della CA) verranno creati nella directory certs locale.

Output atteso:

Generating a new CA in /certs
CA certificate: /certs/ca.crt
CA private key: /certs/ca.key

Generazione di un certificato TLS per un dominio

Ora che abbiamo una CA, possiamo generare un certificato TLS per un dominio specifico. Ad esempio, generiamo un certificato per example.com:

docker exec -it certctl certctl cert example.com

Questo comando genera un certificato TLS per example.com nella directory /certs all’interno del container certctl. I file example.com.crt e example.com.key (certificato e chiave privata) verranno creati nella directory certs locale.

Output atteso:

Generating a new certificate for example.com in /certs
Certificate: /certs/example.com.crt
Private key: /certs/example.com.key

Verifica del certificato (opzionale)

Se hai configurato Nginx, puoi verificare il certificato aprendo un browser e navigando su https://localhost. Il browser dovrebbe visualizzare una pagina di avviso che il certificato non è considerato attendibile (poiché è self-signed). Puoi ignorare l’avviso e procedere. Dovresti visualizzare la pagina predefinita di Nginx, indicando che il certificato TLS funziona correttamente.

Rinnovo dei certificati

I certificati TLS hanno una data di scadenza. certctl semplifica anche il processo di rinnovo. Per rinnovare il certificato per example.com, esegui il seguente comando:

docker exec -it certctl certctl renew example.com

Questo comando rinnova il certificato per example.com e sovrascrive i file esistenti example.com.crt e example.com.key. Se hai configurato Nginx, dovrai ricaricare la configurazione di Nginx per applicare le modifiche:

docker exec -it nginx-test nginx -s reload

Automazione del rinnovo dei certificati

Per automatizzare il rinnovo dei certificati, puoi creare un cron job che esegue il comando certctl renew periodicamente. Ad esempio, per rinnovare i certificati ogni mese, puoi aggiungere la seguente riga al crontab:

0 0 1 * * docker exec -it certctl certctl renew example.com && docker exec -it nginx-test nginx -s reload

Questo comando eseguirà il comando certctl renew e ricaricherà Nginx il primo giorno di ogni mese.

Errori comuni e risoluzione

• Errore: certctl: command not found: Assicurati che certctl sia installato correttamente e che sia disponibile nel PATH del sistema.
• Errore: x509: certificate signed by unknown authority nel browser: Questo errore indica che il certificato è self-signed e non è considerato attendibile da un’autorità di certificazione riconosciuta. Puoi ignorare l’avviso nel browser o aggiungere il certificato della CA al trust store del sistema operativo per evitare l’avviso.
• Errore: Nginx non utilizza il nuovo certificato dopo il rinnovo: Assicurati di ricaricare la configurazione di Nginx dopo aver rinnovato il certificato. Usa il comando docker exec -it nginx-test nginx -s reload.

Conclusione

In questo tutorial, hai imparato come utilizzare certctl e Docker Compose per gestire i certificati TLS self-hosted. Hai visto come generare una CA, creare certificati per domini specifici, rinnovare i certificati e automatizzare il processo di rinnovo. Questo approccio è particolarmente utile per ambienti di sviluppo e test, dove la velocità e la semplicità sono fondamentali. Ricorda che i certificati self-signed non sono adatti per ambienti di produzione, dove è necessario utilizzare certificati emessi da un’autorità di certificazione riconosciuta. Hai domande o suggerimenti? Lascia un commento qui sotto!