TLS Cert Management

Snakeway supports automated TLS certificate issuance and renewal through the ACME protocol (used by Let's Encrypt), as well as manual certificate management for environments where operators provide their own certificates.

Automated TLS with ACME

When ACME is enabled, Snakeway handles the full certificate lifecycle: it requests certificates from the ACME directory, completes the HTTP-01 challenge, stores the issued certificate, and renews it automatically before expiration. No external tooling or cron jobs are required.

Complete Configuration Example

server {
  tls_automation = {
    renew_within_days = 30
    acme = {
      directory_url = "https://acme-v02.api.letsencrypt.org/directory"
      data_dir      = "/var/lib/snakeway/acme"
      contact_email = ["admin@example.com"]
    }
    cert_store = {
      type     = "filesystem"
      cert_dir = "/var/lib/snakeway/acme/certs"
    }
  }
}

The corresponding ingress file must declare ACME mode and the domains to cover:

bind = {
  tls = {
    mode      = "acme"
    domains   = ["example.com", "api.example.com"]
    challenge = "http01"
  }
}

ACME Issuance and Renewal Flow

1. On startup, Snakeway checks the configured cert store for existing certificates covering the declared domains.
2. If no valid certificate exists, or if an existing certificate will expire within renew_within_days, Snakeway initiates an ACME order with the configured directory URL.
3. Snakeway completes the HTTP-01 challenge by serving the ACME token on the /.well-known/acme-challenge/ path.
4. Once the certificate authority validates the challenge, Snakeway retrieves the issued certificate and stores it in the configured cert store.
5. Snakeway periodically re-checks certificate expiry and repeats the renewal process as needed.

The renew_within_days parameter controls how early renewal begins. A value of 30 means Snakeway will attempt renewal when the certificate has 30 or fewer days until expiration. Values between 7 and 30 are typical; lower values reduce unnecessary renewals, while higher values provide a larger buffer against transient ACME failures.

Certificate Stores

Snakeway supports two built-in certificate stores, each suited to different deployment scenarios.

Filesystem store persists certificates to disk. This is the recommended store for production. Certificates survive process restarts without re-issuance, and the files can be backed up or inspected by operators.

cert_store = {
  type     = "filesystem"
  cert_dir = "/var/lib/snakeway/acme/certs"
}

Memory store holds certificates only in process memory. Certificates are lost on restart, which triggers a fresh ACME issuance. This store is useful for development, testing, and ephemeral environments where persistence is unnecessary.

cert_store = {
  type = "memory"
}

caution

The memory store will request a new certificate from the ACME provider on every restart. Let's Encrypt enforces rate limits that can block issuance if you restart frequently. Use the filesystem store in production.

Manual Certificate Management

For environments where certificates are provisioned externally (purchased from a CA, generated by an internal PKI, or managed by another tool), configure the ingress bind block with paths to the PEM-encoded certificate and private key:

bind = {
  tls = {
    mode = "manual"
    cert = "/path/to/certs/server.pem"
    key  = "/path/to/certs/server.key"
  }
}

Snakeway reads the certificate and key files at startup. To rotate a manual certificate, replace the files on disk and trigger a configuration reload via the Admin API or by sending SIGHUP.

Monitoring and Failure Recovery

Monitor certificate expiry. Even with automated renewal, operators should monitor certificate expiration dates. If ACME renewal fails (network issues, DNS misconfiguration, rate limits), the existing certificate continues to serve traffic until it expires.

Check logs for renewal errors. Snakeway logs ACME interactions at the info level and errors at warn or error. Watch for repeated renewal failures and investigate the underlying cause promptly.

Verify the challenge path is reachable. HTTP-01 challenges require that /.well-known/acme-challenge/ on port 80 is accessible from the internet. If a firewall, CDN, or upstream load balancer blocks this path, ACME validation will fail.