このページは、まだ日本語ではご利用いただけません。翻訳中です。
Using the plugin
You can follow the basic examples to enable your plugin using your preferred method. Or, follow this guide to set up and test the plugin from start to finish.
Prerequisites
- Kong needs to listen on port 80 or proxy a load balancer that listens for port 80.
-
lua_ssl_trusted_certificate
needs to be set inkong.conf
to ensure the plugin can properly verify the Let’s Encrypt API. The CA-bundle file is usually/etc/ssl/certs/ca-certificates.crt
for Ubuntu/Debian and/etc/ssl/certs/ca-bundle.crt
for CentOS/Fedora/RHEL. Starting with Kong v2.2, users can set this config tosystem
to auto pick CA-bundle from OS.
Getting started with the ACME plugin
For each the domain that needs a certificate, make sure DOMAIN/.well-known/acme-challenge
is mapped to a route in Kong. You can check this by sending
curl KONG_IP/.well-known/acme-challenge/x -H "host:DOMAIN"
and getting the response Not found
.
You can also use the Admin API to verify the setup.
If not, add a route and a dummy service to catch this route.
-
Add a sample service if needed:
curl http://localhost:8001/services \ --data "name=acme-example" \ --data "url=http://127.0.0.1:65535"
-
Add a sample route if needed:
curl http://localhost:8001/routes \ --data "name=acme-example" \ --data "paths[]=/.well-known/acme-challenge" \ --data "service.name=acme-example"
-
Enable the plugin:
curl http://localhost:8001/plugins \ --data "name=acme" \ --data "config.account_email=yourname@yourdomain.com" \ --data "config.tos_accepted=true" \ --data "config.domains[]=my.secret.domains.com" \ --data "config.storage=kong"
This example uses kong
storage for demo purposes, which stores the certificate in the Kong database.
kong
storage is not supported in DB-less mode or Konnect, use one of the other storage options instead.
Setting tos_accepted
to true implies that you have read and accepted
terms of service.
This plugin can only be configured as a global plugin. The plugin terminates
/.well-known/acme-challenge/
path for matching domains. To create certificates
and terminate challenges only for certain domains, refer to the
Parameters section.
Trigger certificate creation
Assume Kong proxy is accessible via http://mydomain.com and https://mydomain.com.
-
Run a sanity test on your Kong setup before creating any certificate:
curl http://localhost:8001/acme \ --data "host=mydomain.com" \ --data "test_http_challenge_flow=true"
-
Trigger certificate creation:
You can trigger asynchronous creation from proxy requests.
The following request returns Kong’s default certificate:
curl https://mydomain.com -k
Wait up to 1 minute for the background process to finish.
Or, create it synchronously from the Admin API:
curl http://localhost:8001/acme -d host=mydomain.com
You can also use this endpoint to force renew a certificate.
-
Now, the following request gives you a valid Let’s Encrypt certificate:
curl https://mydomain.com
Renew certificates
The plugin runs daily checks and automatically renews all certificates that
will expire in less than the configured renew_threshold_days
value. If the renewal
of an individual certificate throws an error, the plugin will continue renewing the
other certificates. It will try renewing all certificates, including those that previously
failed, once per day. Note the renewal configuration is stored in the configured storage backend.
If the storage is cleared or modified outside of Kong, renewal might not complete properly.
It’s also possible to actively trigger the renewal. The following request schedules a renewal in the background and returns immediately.
curl http://localhost:8001/acme -XPATCH
More information
- Local testing and development guide
- Monitoring and debugging: The ACME plugin exposes monitoring and debugging endpoints through the Kong Gateway Admin API. See the ACME API reference for more information.
- ACME plugin configuration reference and basic configuration examples