<commit_before>---
name: ACME
publisher: Kong Inc.
version: 0.2.0

source_url: https://github.com/Kong/kong-plugin-acme

desc: Let's Encrypt and ACMEv2 integration with Kong
description: |
  This plugin allows Kong to apply certificates from Let's Encrypt or any other ACMEv2 service and serve dynamically. Renew is handled with a configurable threshold time.

type: plugin
categories:
  - security

kong_version_compatibility:
    community_edition:
      compatible:
        - 2.0.x
    enterprise_edition:
      compatible:

params:
  name: acme
  api_id: false
  service_id: false
  route_id: false
  consumer_id: false
  protocols: ['http', 'https', 'tcp', 'tls', 'grpc', 'grpcs']
  dbless_compatible: yes
  config:
    - name: account_email
      required: yes
      default:
      description: |
        The account identifier, can be reused in different plugin instance.
    - name: api_uri
      required: false
      default: "`https://acme-v02.api.letsencrypt.org`"
      description: |
        The ACMEv2 API endpoint to use, user might use [Let's Encrypt staging environemnt](https://letsencrypt.org/docs/staging-environment/) during testing.
    - name: cert_type
      required: false
      default: "`rsa`"
      description: |
        The certificate type to create, choice of `"rsa"` for RSA certificate or `"ecc"` for EC certificate.
    - name: domains
      required: false
      default: "`[]`"
      description: |
        The list of domains to create certificate for. To match subdomains under `example.com`, use `*.example.com`. Regex pattern is not supported. Note this config is only used to match domains, not to specify the Common Name or Subject Alternative Name to create certifcates; each domain will have its own certificate.
    - name: renew_threshold_days
      required: false
      default: "`14`"
      description: |
        Days before expire to renew the certificate.
    - name: storage
      required: false
      default: "`shm`"
      description: |
        The backend storage type to use, choice of `"kong"`, `"shm"`, `"redis"`, `"consul"` or `"vault"`. In dbless mode, `"kong"` storage is unavailable.
    - name: storage_config
      required: false
      default:
      description: |
        Storage configs for each backend storage. See below for its default value.
    - name: tos_accepted
      required: false
      default: "`false`"
      description: |
        If you are using Let's Encrypt, you must set this to true to agree the [Terms of Service](https://letsencrypt.org/repository/).
  extra: |
    `config.storage_config` is a table for all posisble storage types, by default it is:
    ```json
        "storage_config": {
          "kong": {},
          "shm": {
            "shm_name": "kong"
          },
          "redis": {
            "auth": null,
            "port": 6379,
            "database": 0,
            "host": "127.0.0.1"
          },
          "consul": {
            "host": "127.0.0.1",
            "port": 8500,
            "token": null,
            "kv_path": "acme"
          },
          "vault": {
            "host": "127.0.0.1",
            "port": 8200,
            "token": null,
            "kv_path": "acme"
          },
        }
    ```

    If you are using a cluster of Kong (multiple Kong instances running on different machines),
    consider using one of `"kong"`, `"redis"`, `"consul"` or `"vault"` to support inter-cluster communication.

    To configure storage type other than `kong`, please refer to [lua-resty-acme](https://github.com/fffonion/lua-resty-acme#storage-adapters).

---

### Using the Plugin

#### Configure Kong

- Kong needs to listen 80 port or proxied by a load balancer that listens for 80 port.
- `nginx_proxy_lua_ssl_trusted_certificate` needs to be set in `kong.conf` to ensure the plugin can properly
verify 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.

#### Enable the Plugin
```bash
$ curl http://localhost:8001/plugins \
        -d name=acme \
        -d config.account_email=<EMAIL> \
        -d config.tos_accepted=true \
        -d config.domains[]=my.secret.domains.com
```

Note by setting `tos_accepted` to *true* implies that you have read and accepted
[terms of service](https://letsencrypt.org/repository/).

**This plugin can only be configured as a global plugin.** The plugin terminates
`/.well-known/acme-challenge/` path for matching domains. To create certificate
and terminates challenge only for certain domains, please refer to the
[Plugin Config](#plugin-config) section.

#### Trigger creation of certificate

Assume Kong proxy is accessible via http://mydomain.com and https://mydomain.com.

```bash
$ curl https://mydomain.com -k
# Returns Kong's default certificate
# Wait up to 1 minute
$ curl https://mydomain.com
# Now gives you a valid Let's Encrypt certicate
```<commit_msg>docs(plugins/acme) add doc for dummy route setup and staging cleaning (#1843)<commit_after>---
name: ACME
publisher: Kong Inc.
version: 0.2.2

source_url: https://github.com/Kong/kong-plugin-acme

desc: Let's Encrypt and ACMEv2 integration with Kong
description: |
  This plugin allows Kong to apply certificates from Let's Encrypt or any other ACMEv2 service and serve dynamically. Renewal is handled with a configurable threshold time.

type: plugin
categories:
  - security

kong_version_compatibility:
    community_edition:
      compatible:
        - 2.0.x
    enterprise_edition:
      compatible:

params:
  name: acme
  api_id: false
  service_id: false
  route_id: false
  consumer_id: false
  protocols: ['http', 'https', 'tcp', 'tls', 'grpc', 'grpcs']
  dbless_compatible: yes
  config:
    - name: account_email
      required: yes
      default:
      description: |
        The account identifier, can be reused in different plugin instance.
    - name: api_uri
      required: false
      default: "`https://acme-v02.api.letsencrypt.org`"
      description: |
        The ACMEv2 API endpoint to use. You can use the [Let's Encrypt staging environment](https://letsencrypt.org/docs/staging-environment/) during testing. Note that Kong doesn't automatically delete staging certificates: if you use same domain to test and use in production, you will need to delete those certificates manually after testing.
    - name: cert_type
      required: false
      default: "`rsa`"
      description: |
        The certificate type to create, choice of `"rsa"` for RSA certificate or `"ecc"` for EC certificate.
    - name: domains
      required: false
      default: "`[]`"
      description: |
        The list of domains to create certificate for. To match subdomains under `example.com`, use `*.example.com`. Regex pattern is not supported. Note this config is only used to match domains, not to specify the Common Name or Subject Alternative Name to create certifcates; each domain will have its own certificate.
    - name: renew_threshold_days
      required: false
      default: "`14`"
      description: |
        Days before expire to renew the certificate.
    - name: storage
      required: false
      default: "`shm`"
      description: |
        The backend storage type to use, choice of `"kong"`, `"shm"`, `"redis"`, `"consul"` or `"vault"`. In dbless mode, `"kong"` storage is unavailable.
    - name: storage_config
      required: false
      default:
      description: |
        Storage configs for each backend storage. See below for its default value.
    - name: tos_accepted
      required: false
      default: "`false`"
      description: |
        If you are using Let's Encrypt, you must set this to true to agree the [Terms of Service](https://letsencrypt.org/repository/).
  extra: |
    `config.storage_config` is a table for all posisble storage types, by default it is:
    ```json
        "storage_config": {
          "kong": {},
          "shm": {
            "shm_name": "kong"
          },
          "redis": {
            "auth": null,
            "port": 6379,
            "database": 0,
            "host": "127.0.0.1"
          },
          "consul": {
            "host": "127.0.0.1",
            "port": 8500,
            "token": null,
            "kv_path": "acme"
          },
          "vault": {
            "host": "127.0.0.1",
            "port": 8200,
            "token": null,
            "kv_path": "acme"
          },
        }
    ```

    If you are using a cluster of Kong (multiple Kong instances running on different machines),
    consider using one of `"kong"`, `"redis"`, `"consul"` or `"vault"` to support inter-cluster communication.

    To configure storage type other than `kong`, please refer to [lua-resty-acme](https://github.com/fffonion/lua-resty-acme#storage-adapters).

---

### Using the Plugin

#### Configure Kong

- Kong needs to listen 80 port or proxied by a load balancer that listens for 80 port.
- `nginx_proxy_lua_ssl_trusted_certificate` needs to be set in `kong.conf` to ensure the plugin can properly
verify 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.

#### Enable the 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`.
If not, add a Route and a dummy Service to catch this route.
```bash
# add a dummy service if needed
$ curl http://localhost:8001/service \
        -d name=acme-dummy \
        -d url=http://127.0.0.1:65535

# add a dummy route if needed
$ curl http://localhost:8001/routes \
        -d name=acme-dummy \
        -d paths[]=/.well-known/acme-challenge \
        -d service.name=acme-dummy

# add the plugin
$ curl http://localhost:8001/plugins \
        -d name=acme \
        -d config.account_email=<EMAIL> \
        -d config.tos_accepted=true \
        -d config.domains[]=my.secret.domains.com
```

Note by setting `tos_accepted` to *true* implies that you have read and accepted
[terms of service](https://letsencrypt.org/repository/).

**This plugin can only be configured as a global plugin.** The plugin terminates
`/.well-known/acme-challenge/` path for matching domains. To create certificate
and terminates challenge only for certain domains, please refer to the
[Plugin Config](#plugin-config) section.

#### Trigger creation of certificate

Assume Kong proxy is accessible via http://mydomain.com and https://mydomain.com.

```bash
$ curl https://mydomain.com -k
# Returns Kong's default certificate
# Wait up to 1 minute
$ curl https://mydomain.com
# Now gives you a valid Let's Encrypt certicate
```
{'fraction_non_alphanumeric': 0.10904722299232973, 'fraction_numerical': 0.011736438406801589, 'mean_word_length': 2.7163461538461537, 'pattern_counts': {'":': 38, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 7, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4715311', 'n_tokens_mistral': 3336, 'n_tokens_neox': 3170, 'n_words': 1146}