ACME Configuration

You are browsing documentation for an outdated plugin version.

Configuration

This plugin is compatible with DB-less mode.

Compatible protocols

The ACME plugin is compatible with the following protocols:

grpc, grpcs, http, https

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

• name or plugin

  string required

  The name of the plugin, in this case acme.

  • If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is name.
  • If using the KongPlugin object in Kubernetes, the field is plugin.

• instance_name

  string

  An optional custom name to identify an instance of the plugin, for example acme_my-service.

  The instance name shows up in Kong Manager and in Konnect, so it's useful when running the same plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance via the Kong Admin API.

  An instance name must be unique within the following context:

  • Within a workspace for Kong Gateway Enterprise
  • Within a control plane or control plane group for Konnect
  • Globally for Kong Gateway (OSS)

• enabled

  boolean default: true

  Whether this plugin will be applied.

• config

  record required
  • account_email

    string required referenceable encrypted matches: %w*%p*@+%w*%.?%w*

    The account identifier. Can be reused in a different plugin instance.

  • account_key

    record

    A private key to use as the account key required by some issuers. This parameter is configured to use Key and Key Sets.

    • key_id

      string required

    • key_set

      string

  • api_uri

    string default: https://acme-v02.api.letsencrypt.org/directory

    The ACMEv2 API endpoint to use. You can specify the Let’s Encrypt staging environment for testing. Kong doesn’t automatically delete staging certificates. If you use the same domain in test and production environments, you need to manually delete those certificates after testing.

  • tos_accepted

    boolean default: false

    If you are using Let’s Encrypt, you must set this to true to agree the Terms of Service.

  • eab_kid

    string referenceable encrypted

    External account binding (EAB) key id. You usually don’t need to set this unless it is explicitly required by the CA.

  • eab_hmac_key

    string referenceable encrypted

    External account binding (EAB) base64-encoded URL string of the HMAC key. You usually don’t need to set this unless it is explicitly required by the CA.

  • cert_type

    string default: rsa Must be one of: rsa, ecc

    The certificate type to create. The possible values are 'rsa' for RSA certificate or 'ecc' for EC certificate.

  • rsa_key_size

    number default: 4096 Must be one of: 2048, 3072, 4096

    RSA private key size for the certificate. The possible values are 2048, 3072, or 4096.

  • renew_threshold_days

    number default: 14

    Days remaining to renew the certificate before it expires.

  • domains

    array of type string

    The list of domains to create certificates for. To match subdomains under example.com, use *.example.com. Regex pattern is not supported.

    This parameter is only used to match domains, not to specify the Common Name or Subject Alternative Name to create certificates. Each domain must have its own certificate. The ACME plugin checks this configuration before checking any certificate in storage when serving the certificate of a request.

    If this field is left empty, all top-level domains (TLDs) are allowed.

  • allow_any_domain

    boolean default: false

    If set to true, the plugin allows all domains and ignores any values in the domains list.

  • fail_backoff_minutes

    number default: 5

    Minutes to wait for each domain that fails to create a certificate. This applies to both a new certificate and a renewal certificate.

  • storage

    string default: shm Must be one of: kong, shm, redis, consul, vault

    The backend storage type to use. The possible values are 'kong', 'shm', 'redis', 'consul', or 'vault'. In DB-less mode, 'kong' storage is unavailable. Note that 'shm' storage does not persist during Kong restarts and does not work for Kong running on different machines, so consider using one of 'kong', 'redis', 'consul', or 'vault' in production. Please refer to the Hybrid Mode sections below as well.

  • storage_config

    record required
    • shm

      record required
      • shm_name

        string default: kong

    • kong

      record required

    • redis

      record required
      • host

        string

      • port

        integer between: 0 65535

      • database

        number

      • auth

        string referenceable

      • ssl

        boolean required default: false

      • ssl_verify

        boolean required default: false

      • ssl_server_name

        string

      • namespace

        string required len_min: 0

    • consul

      record required
      • https

        boolean default: false

      • host

        string

      • port

        integer between: 0 65535

      • kv_path

        string

      • timeout

        number

      • token

        string referenceable

    • vault

      record required
      • https

        boolean default: false

      • host

        string

      • port

        integer between: 0 65535

      • kv_path

        string

      • timeout

        number

      • token

        string referenceable

      • tls_verify

        boolean default: true

      • tls_server_name

        string

      • auth_method

        string default: token Must be one of: token, kubernetes

      • auth_path

        string

      • auth_role

        string

      • jwt_path

        string

  • preferred_chain

    string

  • enable_ipv4_common_name

    boolean default: true