Flush a public Dedicated Cloud Gateway managed cache using Terraform

This how-to deploys a custom Kong plugin that exposes a flush endpoint on your gateway. Calling the endpoint authenticates to the managed cache with AWS STS-derived credentials and runs FLUSHDB, so you (or your CI/CD pipeline) can flush the cache without engineering involvement.

First, create and configure the custom plugin:

1. Create a schema.lua file that defines the plugin’s configuration fields.

      echo '
      local typedefs = require "kong.db.schema.typedefs"
   
      return {
        name = "cache-flusher",
        fields = {
          { protocols = typedefs.protocols_http },
          {
            config = {
              type = "record",
              fields = {
              { host = typedefs.host({ default = "127.0.0.1", referenceable = true }) },
              { port = typedefs.port({ default = 6379, referenceable = true }) },
              { username = { type = "string", referenceable = true } },
              { ssl = { type = "boolean", default = true } },
              { server_name = { type = "string", referenceable = true } },
              { cloud_authentication = {
                  type = "record",
                  fields = {
                    { auth_provider = { type = "string", referenceable = true } },
                    { aws_region = { type = "string", referenceable = true } },
                    { aws_assume_role_arn = { type = "string", referenceable = true } },
                    { aws_cache_name = { type = "string", referenceable = true } },
                  }
              }},
            }
            },
          },
        },
      }
      ' > schema.lua

   Copied!

   Toggle code

2. Create a handler.lua file that authenticates to the managed cache and runs the flush.

      echo '
      local AWS = require "resty.aws"
      local redis = require "resty.redis"
      local aws_config = require "resty.aws.config"
   
      local AWS_DEFAULT_ROLE_SESSION_NAME = "KongElasticacheSession"
      local AWS_global_config = aws_config.global
      local aws = AWS({ region = AWS_global_config.region })
   
      local plugin = {
        PRIORITY = 980,
        VERSION  = "1.0.0",
      }
   
      local function get_aws_auth_token(conf, cloud_auth)
          local cachename = cloud_auth.aws_cache_name
          local name = conf.username
          local region = cloud_auth.aws_region
          local assume_role_arn = cloud_auth.aws_assume_role_arn
   
          local credentials = aws.config.credentials
   
          local sts, err = aws:STS({
              region = region,
              credentials = credentials,
              stsRegionalEndpoints = AWS_global_config.sts_regional_endpoints,
          })
          if not sts then
              return nil, err
          end
   
          local creds = aws:ChainableTemporaryCredentials {
              params = {
                  RoleArn = assume_role_arn,
                  RoleSessionName = AWS_DEFAULT_ROLE_SESSION_NAME,
              },
              sts = sts,
          }
   
          local cache = aws:ElastiCache({ region = region })
   
          local signer = cache:Signer {
              cachename = cachename,
              username = name,
              is_serverless = false,
              region = region,
              credentials = creds,
          }
   
          local auth_token, token_err = signer:getAuthToken()
          if token_err then
              return nil, token_err
          end
   
          return auth_token
      end
   
      local function get_auth_token(conf)
          local cloud_auth = conf.cloud_authentication
          local provider = cloud_auth.auth_provider
   
          if provider == "aws" then
              return get_aws_auth_token(conf, cloud_auth)
          end
   
          return nil, "cloud provider " .. tostring(provider) .. " not implemented"
      end
   
      function plugin:access(conf)
          kong.log.notice("[cache-flusher] starting cache flush")
   
          -- Connect to Cache
          kong.log.notice("[cache-flusher] connecting to Cache at ", conf.host, ":", conf.port)
   
          local red = redis:new()
          local ok, err = red:connect(conf.host, conf.port, {
              ssl = conf.ssl,
              ssl_verify = conf.ssl,
              server_name = conf.server_name,
          })
          if not ok then
              kong.log.err("[cache-flusher] failed to connect to Cache: ", err)
              return kong.response.error(500, "cache flush failed: Cache connect error")
          end
   
          kong.log.notice("[cache-flusher] connected to Cache, obtaining auth token")
   
          -- Authenticate with STS-derived token
          local auth_token, token_err = get_auth_token(conf)
          if not auth_token then
              kong.log.err("[cache-flusher] failed to obtain auth token: ", token_err)
              return kong.response.error(500, "cache flush failed: auth token error")
          end
   
          kong.log.notice("[cache-flusher] auth token obtained, authenticating with Cache")
   
          local res, auth_err = red:auth(conf.username, auth_token)
          if not res then
              kong.log.err("[cache-flusher] failed to authenticate with Cache: ", auth_err)
              return kong.response.error(500, "cache flush failed: Cache auth error")
          end
   
          kong.log.notice("[cache-flusher] authenticated, flushing Cache")
   
          -- Flush Cache
          local flush_res, flush_err = red:flushdb("ASYNC")
          if not flush_res then
              kong.log.err("[cache-flusher] failed to flush Cache: ", flush_err)
              return kong.response.error(500, "cache flush failed: Cache flushdb error")
          end
   
          kong.log.notice("[cache-flusher] cache flush completed successfully")
   
          return kong.response.exit(200, { message = "[cache-flusher] cache flushed" })
      end
   
      return plugin
      ' > handler.lua

   Copied!

   Toggle code

3. Declare the variables this how-to uses, and export the ones only you know:

    echo '
    variable "control_plane_id" {
      type = string
    }
   
    variable "flush_path" {
      type    = string
      default = "/konnect/managed-cache/flush"
    }
   
    variable "ip_allowlist" {
      type    = list(string)
      default = []
    }
   
    variable "auto_flush" {
      type    = bool
      default = false
    }
   
    variable "proxy_hostname" {
      type = string
    }
    ' > variables.tf

   Copied!

   Toggle code

   If you created your control plane as part of the prereqs, get its ID directly from Terraform state:

    export TF_VAR_control_plane_id=$(terraform output -raw control_plane_id)

   Copied!

   Otherwise, export the ID of your existing control plane:

    export TF_VAR_control_plane_id="your-control-plane-id"

   Copied!

4. Look up the Konnect proxy hostname for your control plane, and export it as a Terraform variable:

   CONTROL_PLANE_DETAILS=$(curl -X GET "https://us.api.konghq.com/v2/control-planes/$TF_VAR_control_plane_id" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN"
   )

   Copied!

5. Export the proxy hostname:

   PROXY_HOSTNAME=$(echo $CONTROL_PLANE_DETAILS | jq -r '.config.control_plane_endpoint | sub("https://";"") | split(".")[0]')
   export TF_VAR_proxy_hostname="${PROXY_HOSTNAME}.gateways.konggateway.com"

   Copied!

6. Define the custom plugin, the Gateway Service and Route that expose the flush endpoint, and the plugin instance:

    echo '
    resource "konnect_gateway_custom_plugin_streaming" "cache_flusher" {
      control_plane_id = var.control_plane_id
      name             = "cache-flusher"
      schema           = file("${path.module}/schema.lua")
      handler          = file("${path.module}/handler.lua")
    }
   
    resource "konnect_gateway_service" "cache_flusher_service" {
      control_plane_id = var.control_plane_id
      name             = "managed-cache-flush-service"
      host             = "127.0.0.1"
      port             = 443
      protocol         = "https"
    }
   
    resource "konnect_gateway_route" "cache_flusher_route" {
      control_plane_id = var.control_plane_id
      service = {
        id = konnect_gateway_service.cache_flusher_service.id
      }
      paths = [var.flush_path]
    }
   
    resource "konnect_gateway_custom_plugin" "cache_flusher_instance" {
      name             = "cache-flusher"
      control_plane_id = var.control_plane_id
      enabled          = true
      service = {
        id = konnect_gateway_service.cache_flusher_service.id
      }
      route = {
        id = konnect_gateway_route.cache_flusher_route.id
      }
      config = {
        "cloud_authentication" : {
          "auth_provider" : "{vault://env/ADDON_MANAGED_CACHE_AUTH_PROVIDER}",
          "aws_assume_role_arn" : "{vault://env/ADDON_MANAGED_CACHE_AWS_ASSUME_ROLE_ARN}",
          "aws_cache_name" : "{vault://env/ADDON_MANAGED_CACHE_AWS_CACHE_NAME}",
          "aws_region" : "{vault://env/ADDON_MANAGED_CACHE_AWS_REGION}"
        },
        "host" : "{vault://env/ADDON_MANAGED_CACHE_HOST}",
        "port" : "{vault://env/ADDON_MANAGED_CACHE_PORT}",
        "server_name" : "{vault://env/ADDON_MANAGED_CACHE_SERVER_NAME}",
        "ssl" : true,
        "username" : "{vault://env/ADDON_MANAGED_CACHE_USERNAME}"
      }
   
      depends_on = [konnect_gateway_custom_plugin_streaming.cache_flusher]
    }
    ' >> main.tf

   Copied!

   Toggle code

   The {vault://env/ADDON_MANAGED_CACHE_*} references are populated automatically by Konnect once your managed cache add-on reaches a Ready state, so you don’t need to configure any AWS IAM credentials yourself.

7. Add an output for the flush URL:

    echo '
    output "flush_proxy_url" {
      value = "https://${var.proxy_hostname}${var.flush_path}"
    }
    ' > output.tf

   Copied!

8. Apply the configuration:

    terraform apply -auto-approve

   Copied!

   You’ll get a response like the following:

    Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Strongly recommended: Restrict access and auto-flush on apply

Use the following sections to further configure the managed cache flush behavior.

Limit IPs that can trigger a flush

If you want to limit which IPs can trigger a flush, set ip_allowlist to a list of IPs or CIDRs, and add an ip-restriction plugin scoped to the flush route.

1. Configure the IP Restriction plugin:

   echo '
   resource "konnect_gateway_plugin_ip_restriction" "ip-restriction-plugin" {
     count = length(var.ip_allowlist) > 0 ? 1 : 0
   
     config = {
       allow = var.ip_allowlist
   
       message = "NOT ALLOWED"
       status  = 405
     }
   
     control_plane_id = var.control_plane_id
     enabled          = true
     service = {
       id = konnect_gateway_service.cache_flusher_service.id
     }
     route = {
       id = konnect_gateway_route.cache_flusher_route.id
     }
   }
   ' >> main.tf

   Copied!

   Toggle code

2. Export the IPs you want to allow list:

   export TF_VAR_ip_allowlist='["203.0.113.0/24"]'

   Copied!

3. Apply the Terraform configuration:

   terraform apply -auto-approve

   Copied!

Requests from IPs outside the allowlist receive a 405 response.

Automatically flush on terraform apply

1. If you want the cache to flush automatically every time you run terraform apply, set auto_flush to true:

   echo '
   resource "terraform_data" "flush_cache" {
     count = var.auto_flush ? 1 : 0
   
     triggers_replace = [timestamp()]
   
     provisioner "local-exec" {
       command = "sleep 10 && curl -sf https://${var.proxy_hostname}${var.flush_path}"
     }
   
     depends_on = [
       konnect_gateway_route.cache_flusher_route,
       konnect_gateway_custom_plugin.cache_flusher_instance,
       konnect_gateway_plugin_ip_restriction.ip-restriction-plugin,
     ]
   }
   ' >> main.tf

   Copied!

   Toggle code

2. Export the auto flush behavior:

   export TF_VAR_auto_flush=true

   Copied!

3. Apply the Terraform configuration:

   terraform apply -auto-approve

   Copied!

When auto_flush is true, every terraform apply triggers a cache flush, not just the first one. Subsequent applies also show the terraform_data.flush_cache resource being destroyed and recreated. This is expected and can be safely ignored.

Trigger a flush by calling the URL Terraform output in the previous step:

curl -sf "$(terraform output -raw flush_proxy_url)"

A successful flush returns:

{"message": "[cache-flusher] cache flushed"}