ACME Configuration

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

    The private key associated with the account.

    • key_id

      string required

      The Key ID.

    • key_set

      string

      The ID of the key set to associate the Key ID with.

  • api_uri

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

    A string representing a URL, such as https://example.com/path/to/resource?q=search.

  • 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

    An array of strings representing hosts. A valid host is a string containing one or more labels separated by periods, with at most one wildcard label (‘*’)

  • 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

        Name of shared memory zone used for Kong API gateway storage

    • kong

      record required

    • redis

      record required
      • host

        string

        A string representing a host name, such as example.com.

      • port

        integer default: 6379 between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

      • timeout

        integer default: 2000 between: 0 2147483646

        An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

      • username

        string referenceable

        Username to use for Redis connections. If undefined, ACL authentication won’t be performed. This requires Redis v6.0.0+. To be compatible with Redis v5.x.y, you can set it to default.

      • password

        string referenceable encrypted len_min: 0

        Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.

      • database

        integer default: 0

        Database to use for the Redis connection when using the redis strategy

      • ssl

        boolean default: false

        If set to true, uses SSL to connect to Redis.

      • ssl_verify

        boolean default: false

        If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure lua_ssl_trusted_certificate in kong.conf to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.

      • server_name

        string

        A string representing an SNI (server name indication) value for TLS.

      • extra_options

        record required

        Custom ACME Redis options

        • namespace

          string required len_min: 0

          A namespace to prepend to all keys stored in Redis.

        • scan_count

          number default: 10

          The number of keys to return in Redis SCAN calls.

    • consul

      record required
      • https

        boolean default: false

        Boolean representation of https.

      • host

        string

        A string representing a host name, such as example.com.

      • port

        integer between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

      • kv_path

        string

        KV prefix path.

      • timeout

        number

        Timeout in milliseconds.

      • token

        string referenceable

        Consul ACL token.

    • vault

      record required
      • https

        boolean default: false

        Boolean representation of https.

      • host

        string

        A string representing a host name, such as example.com.

      • port

        integer between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

      • kv_path

        string

        KV prefix path.

      • timeout

        number

        Timeout in milliseconds.

      • token

        string referenceable

        Consul ACL token.

      • tls_verify

        boolean default: true

        Turn on TLS verification.

      • tls_server_name

        string

        SNI used in request, default to host if omitted.

      • auth_method

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

        Auth Method, default to token, can be ‘token’ or ‘kubernetes’.

      • auth_path

        string

        Vault’s authentication path to use.

      • auth_role

        string

        The role to try and assign.

      • jwt_path

        string

        The path to the JWT.

  • preferred_chain

    string

    A string value that specifies the preferred certificate chain to use when generating certificates.

  • enable_ipv4_common_name

    boolean default: true

    A boolean value that controls whether to include the IPv4 address in the common name field of generated certificates.