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

    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 between: 0 65535

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

      • database

        number

        The index of the Redis database to use.

      • auth

        string referenceable

        The Redis password to use for authentication.

      • ssl

        boolean required default: false

        Whether to use SSL/TLS encryption when connecting to the Redis server.

      • ssl_verify

        boolean required default: false

        Whether to verify the SSL/TLS certificate presented by the Redis server. This should be a boolean value.

      • ssl_server_name

        string

        The expected server name for the SSL/TLS certificate presented by the Redis server.

      • namespace

        string required len_min: 0

        A namespace to prepend to all keys stored in Redis.

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