このページは、まだ日本語ではご利用いただけません。翻訳中です。
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. | ✅ | ✅ 1 | ❌ | ❌ |
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
:
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
- Configuration reference
- Basic configuration example
- Learn how to use the plugin
- Configure the ACME plugin with Redis
- Local testing and development
- ACME plugin API reference