Test certificate generation locally with ngrok and the ACME plugin

Uses: Kong Gateway decK

Deployment Platform:

Prerequisites

Kong Gateway running

This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.

Export your license to an environment variable:

 export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

Run the quickstart script:

 curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA 

Once Kong Gateway is ready, you will see the following message:

 Kong Gateway Ready

decK

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial you will first need to install decK.

ngrok

In this tutorial, we use ngrok to expose a local URL to the internet for local testing and development purposes. This isn’t a requirement for the ACME plugin itself.

Install ngrok.
Sign up for an ngrok account and find your ngrok authtoken.
Install the authtoken and connect the ngrok agent to your account:
```
ngrok config add-authtoken <TOKEN>
```
Run ngrok:
```
ngrok http localhost:8000
```
Copy the Forwarding URL from the output and strip the https://.
In a new terminal window, export it as a decK environment variable:
```
export DECK_NGROK_HOST='YOUR FORWARDING URL'
```

Configure a Service and Route

The ACME plugin requires a Route to access the proxy to trigger certificate generation.

Create a Gateway Service as well as a corresponding Route that points to your ngrok host:

echo '
_format_version: "3.0"
services:
  - name: acme-test
    url: https://httpbin.konghq.com
routes:
  - name: acme-route
    service:
      name: acme-test
    hosts:
    - "${{ env "DECK_NGROK_HOST" }}"
' | deck gateway apply -

Enable the plugin

You can now enable the ACME plugin globally with ngrok as your domain:

echo '
_format_version: "3.0"
plugins:
  - name: acme
    config:
      account_email: test@test.com
      tos_accepted: true
      domains:
      - "${{ env "DECK_NGROK_HOST" }}"
      storage: kong
' | deck gateway apply -

Create a certificate

Trigger certificate creation:

curl https://$DECK_NGROK_HOST:8443 --resolve $DECK_NGROK_HOST:8443:127.0.0.1 -vk

This might take a few seconds.

Validate

Validate that the certificate was correctly created:

echo q |openssl s_client -connect localhost -port 8443 -servername $DECK_NGROK_HOST 2>/dev/null |openssl x509 -text -noout

You should see the certificate in the output.

Cleanup

Destroy the Kong Gateway container

curl -Ls https://get.konghq.com/quickstart | bash -s -- -d