Skip to content
|
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

Getting started with ACME

By Kong Inc.

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 in kong.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 to system 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.

  1. Add a sample service if needed:

     curl http://localhost:8001/services \
   --data "name=acme-example" \
   --data "url=http://127.0.0.1:65535"

  2. 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"

  3. 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.

  1. 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"

  2. 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.

  3. 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