ACME - Plugin - unreleased

You are browsing unreleased documentation.

Looking for the plugin's configuration parameters? You can find them in the ACME configuration reference doc.

The ACME plugin allows Kong Gateway to apply certificates from Let’s Encrypt or any other ACMEv2 service and serve them dynamically. Renewal is handled with a configurable threshold time.

Notes:

The plugin only supports the http-01 challenge, meaning a user needs a public IP and a resolvable DNS. Kong also needs to accept proxy traffic from port 80.

A wildcard or star (*) certificate is not supported. Each domain must have its own certificate.

Supported storage types

You can set the backend storage for the plugin using the config.storage parameter. The backend storage available depends on the topology of your Kong Gateway environment:

Storage type	Description	Traditional mode	Hybrid mode	DB-less	Konnect
`shm`	Lua shared dict storage. This storage is volatile between Nginx restarts (not reloads).	✅	❌	✅	❌
`kong`	Kong database storage.	✅	✅ ¹	❌	❌
`redis`	Redis-based storage.	✅	✅	✅	✅
`consul`	HashiCorp Consul storage.	✅	✅	✅	✅
`vault`	HashiCorp Vault storage. Only the KV V2 backend is supported.	✅	✅	✅	✅

[1]: Due to current the limitations of hybrid mode, kong storage only supports certificate generation from the Admin API but not the proxy side, as the data planes don’t have access to the Kong database. See the hybrid mode workflow for details.

To configure a storage type other than kong, see lua-resty-acme for example configurations.

Running with or without a database

In a database-backed deployment, the plugin creates an SNI and certificate entity in Kong to serve the certificate. If the SNI or certificate for the current request is already set in the database, it will be overwritten.

In DB-less mode, the plugin takes over certificate handling. If the SNI or certificate entity is already defined in Kong, it will be overridden by the response.

Workflow

An http-01 challenge workflow between the Kong Gateway and the ACME server is described below:

The client sends a proxy or Admin API request that triggers certificate generation for mydomain.com.
The Kong Gateway sends a request to the ACME server to start the validation process.
The ACME server returns a challenge response detail to the Kong Gateway.
mydomain.com is publicly resolvable to the Kong Gateway that serves the challenge response.
The ACME server checks if the previous challenge has a response at mydomain.com.
The Kong Gateway checks the challenge status and if passed, downloads the certificate from the ACME server.
The Kong Gateway uses the new certificate to serve TLS requests.

Hybrid mode workflow

kong storage in hybrid mode works in following flow:

The client sends an Admin API request that triggers certificate generation for mydomain.com.
The Kong control plane requests the ACME server to start the validation process.
The ACME server returns a challenge response detail to the Kong control plane.
The Kong control plane propagates the challenge response detail to the Kong data plane.
mydomain.com is publicly resolvable to the Kong data plane that serves the challenge response.
The ACME server checks if the previous challenge has a response at mydomain.com.
The Kong control plane checks the challenge status and if passed, downloads the certificate from the ACME server.
The Kong control plane propagates the new certificates to the Kong data plane.
The Kong data plane uses the new certificate to serve TLS requests.

All external storage types work as usual in hybrid mode. Both the control plane and data planes need to connect to the same external storage cluster. It’s also a good idea to set up replicas to avoid connecting to same node directly for external storage.

External storage in hybrid mode (redis, consul, or vault) works in the following way:

The client send a proxy or Admin API request that triggers certificate generation for mydomain.com.
The Kong control plane or data plane requests the ACME server to start the validation process.
The ACME server returns a challenge response detail to the Kong Gateway.
The Kong control plane or data plane stores the challenge response detail in external storage.
mydomain.com is publicly resolvable to the Kong data plane that reads and serves the challenge response from external storage.
The ACME server checks if the previous challenge has a response at mydomain.com.
The Kong control plane or data plane checks the challenge status and if passed, downloads the certificate from the ACME server.
The Kong control plane or data plane stores the new certificates in external storage.
The Kong data plane reads from external storage and uses the new certificate to serve TLS requests.

EAB support

External account binding (EAB) is supported as long as the eab_kid and eab_hmac_key values are provided.

The following CA provider’s external account can be registered automatically, without specifying the eab_kid or eab_hmac_key:

ZeroSSL

Storage configuration considerations

config.storage_config is a table for all possible storage types. By default, it is:

    "storage_config": {
      "kong": {},
      "shm": {
        "shm_name": "kong"
      },
      "redis": {
        "auth": null,
        "port": 6379,
        "database": 0,
        "host": "127.0.0.1",
        "ssl": false,
        "ssl_verify": false,
        "ssl_server_name": null,
        "namespace": ""
      },
       "consul": {
          "host": "127.0.0.1",
          "port": 8500,
          "token": null,
          "kv_path": "acme",
          "timeout": 2000,
          "https": false
      },
      "vault": {
          "host": "127.0.0.1",
          "port": 8200,
          "token": null,
          "kv_path": "acme",
          "timeout": 2000,
          "https": false,
          "tls_verify": true,
          "tls_server_name": null,
          "auth_method": "token",
          "auth_path": null,
          "auth_role": null,
          "jwt_path": null,
      },
    }

Get started with the ACME plugin

Next ACME Configuration