Kong Cluster Terraform Module for AWS

⚠️ This terraform module serves as reference point for getting started. While it may work for certain scenarios, it is NOT intended to work with all setups. Please fork the repo or copy over code from here (liberal Apache-licensed).

Kong API Gateway is an API gateway microservices management layer. Both Kong and Enterprise Edition are supported.

By default, the following resources will be provisioned:

• RDS PostgreSQL database for Kong's configuration store
• An Auto Scaling Group (ASG) and EC2 instances running Kong (Kong nodes)
• An external load balancer (HTTPS only)
  • HTTPS:443 - Kong Proxy
• An internal load balancer (HTTP and HTTPS)
  • HTTP:80 - Kong Proxy
  • HTTPS:443 - Kong Proxy
  • HTTPS:8444 - Kong Admin API (Enterprise Edition only)
  • HTTPS:8445 - Kong Manager (Enterprise Edition only)
  • HTTPS:8446 - Kong Dev Portal GUI (Enterprise Edition only)
  • HTTPS:8447 - Kong Dev Portal API (Enterprise Edition only)
• Security groups granting least privilege access to resources
• An IAM instance profile for access to Kong specific SSM Parameter Store metadata and secrets

Optionally, a redis cluster can be provisioned for rate-limiting counters and caching, and most default resources can be disabled. See variables.tf for a complete list and description of tunables.

The Kong nodes are based on Minimal Ubuntu. Using cloud-init, the following is provisioned on top of the AMI:

• A kong service user
• Minimal set of dependencies and debugging tools
• decK for Kong declarative configuration management
• Kong, running under runit process supervision
• Log rotation of Kong log files

Prerequisites:

• An AWS VPC
• Private and public subnets tagged with a subnet_tag (default = 'Tier' tag)
• Database subnet group
• Cache subnet group (if enabling Redis)
• An SSH Key
• An SSL managed certificate to associate with HTTPS load balancers

Variables

Name	Description	Type	Default	Required
admin_cidr_blocks	Access to Kong Admin API (Enterprise Edition only)	list(string)	[ "0.0.0.0/0" ]	no
asg_desired_capacity	The number of instances that should be running in the group	string	2	no
asg_health_check_grace_period	Time in seconds after instance comes into service before checking health	string	300	no
asg_max_size	The maximum size of the auto scale group	string	3	no
asg_min_size	The minimum size of the auto scale group	string	1	no
bastion_cidr_blocks	Bastion hosts allowed access to PostgreSQL and Kong Admin	list(string)	[ "127.0.0.1/32" ]	no
ce_pkg	Filename of the Community Edition package	string	"kong-1.3.0.bionic.amd64.deb"	no
cloudwatch_actions	List of cloudwatch actions for Alert/Ok	list(string)	[]	no
db_backup_retention_period	The number of days to retain backups	string	7	no
db_engine_mode	Engine mode for Aurora	string	"provisioned"	no
db_engine_version	Database engine version	string	"11.4"	no
db_family	Database parameter group family	string	"postgres11"	no
db_instance_class	Database instance class	string	"db.t2.micro"	no
db_instance_count	Number of database instances (0 to leverage an existing db)	string	1	no
db_multi_az	Boolean to specify if RDS is multi-AZ	string	false	no
db_storage_size	Size of the database storage in Gigabytes	string	20	no
db_storage_type	Type of the database storage	string	"gp2"	no
db_subnets	Database instance subnet group name	string	"db-subnets"	no
db_username	Database master username	string	"root"	no
deck_version	Version of decK to install	string	"0.5.2"	no
additional_security_groups	IDs of the additional security groups attached to Kong EC2 instance	list(string)	[]	no
deregistration_delay	Seconds to wait before changing the state of a deregistering target from draining to unused	string	300	no
description	Resource description tag	string	"Kong API Gateway"	no
ec2_ami	Map of Ubuntu Minimal AMIs by region	map(string)	{ "us-east-1": "ami-7029320f", "us-east-2": "ami-0350efe0754b8e179", "us-west-1": "ami-657f9006", "us-west-2": "ami-59694f21" }	no
ec2_instance_type	EC2 instance type	string	"t2.micro"	no
ec2_key_name	AWS SSH Key	string	""	no
ec2_root_volume_size	Size of the root volume (in Gigabytes)	string	8	no
ec2_root_volume_type	Type of the root volume (standard, gp2, or io)	string	"gp2"	no
ee_license	Enterprise Edition license key (JSON format)	string	"placeholder"	no
ee_pkg	Filename of the Enterprise Edition package	string	"kong-enterprise-edition-0.36-2.bionic.all.deb"	no
enable_aurora	Boolean to enable Aurora	string	"false"	no
enable_deletion_protection	Boolean to enable delete protection on the ALB	string	true	no
enable_ee	Boolean to enable Kong Enterprise Edition settings	string	false	no
enable_external_lb	Boolean to enable/create the external load balancer, exposing Kong to the Internet	string	true	no
enable_internal_lb	Boolean to enable/create the internal load balancer for the forward proxy	string	true	no
enable_redis	Boolean to enable redis AWS resource	string	false	no
environment	Resource environment tag (i.e. dev, stage, prod)	string	n/a	yes
external_cidr_blocks	External ingress access to Kong Proxy via the load balancer	list(string)	[ "0.0.0.0/0" ]	no
health_check_healthy_threshold	Number of consecutives checks before a unhealthy target is considered healthy	string	5	no
health_check_interval	Seconds between health checks	string	5	no
health_check_matcher	HTTP Code(s) that result in a successful response from a target (comma delimited)	string	200	no
health_check_timeout	Seconds waited before a health check fails	string	3	no
health_check_unhealthy_threshold	Number of consecutive checks before considering a target unhealthy	string	2	no
http_4xx_count	HTTP Code 4xx count threshhold	string	50	no
http_5xx_count	HTTP Code 5xx count threshhold	string	50	no
idle_timeout	Seconds a connection can idle before being disconnected	string	60	no
internal_http_cidr_blocks	Internal ingress access to Kong Proxy via the load balancer (HTTP)	list(string)	[ "0.0.0.0/0" ]	no
internal_https_cidr_blocks	Internal ingress access to Kong Proxy via the load balancer (HTTPS)	list(string)	[ "0.0.0.0/0" ]	no
manager_cidr_blocks	Access to Kong Manager (Enterprise Edition only)	list(string)	[ "0.0.0.0/0" ]	no
manager_host	Hostname to access Kong Manager (Enterprise Edition only)	string	"default"	no
portal_cidr_blocks	Access to Portal (Enterprise Edition only)	list(string)	[ "0.0.0.0/0" ]	no
portal_host	Hostname to access Portal (Enterprise Edition only)	string	"default"	no
private_subnets	Subnet tag on private subnets	string	"private"	no
public_subnets	Subnet tag on public subnets for external load balancers	string	"public"	no
redis_engine_version	Redis engine version	string	"5.0.5"	no
redis_family	Redis parameter group family	string	"redis5.0"	no
redis_instance_count	Number of redis nodes	string	2	no
redis_instance_type	Redis node instance type	string	"cache.t2.small"	no
redis_subnets	Redis cluster subnet group name	string	"cache-subnets"	no
service	Resource service tag	string	"kong"	no
ssl_cert_admin	SSL certificate domain name for the Kong Admin API HTTPS listener	string	n/a	yes
ssl_cert_external	SSL certificate domain name for the external Kong Proxy HTTPS listener	string	n/a	yes
ssl_cert_internal	SSL certificate domain name for the internal Kong Proxy HTTPS listener	string	n/a	yes
ssl_cert_manager	SSL certificate domain name for the Kong Manager HTTPS listener	string	n/a	yes
ssl_cert_portal	SSL certificate domain name for the Dev Portal listener	string	n/a	yes
ssl_policy	SSL Policy for HTTPS Listeners	string	"ELBSecurityPolicy-TLS-1-2-2017-01"	no
subnet_tag	Tag used on subnets to define Tier	string	"Tier"	no
tags	Tags to apply to resources	map	{}	no
vpc_id	VPC ID for the AWS account and region specified	string	n/a	yes
db_final_snapshot_identifier	If specified a final snapshot will be made of the RDS/Aurora instance. If left blank, the finalsnapshot will be skipped	string	""	no

Note: Admin, manager, and portal are Enterprise features. While the SSL certificate needs to be defined, it can be the same as the external and/or internal; however, no resources associated with it are created unless enabled.

Outputs

Name	Description
admin_token	The admin token for Kong
lb_endpoint_external	The external load balancer endpoint
lb_endpoint_internal	The internal load balancer endpoint
master_password	The master password for Kong
rds_endpoint	The endpoint for the Kong database
rds_password	The database password for Kong

Examples

Example main.tf:

provider "aws" {
  region  = "us-west-2"
  profile = "dev"
}

module "kong" {
  source = "github.com/kong/kong-terraform-aws?ref=v3.3"

  vpc                   = "my-vpc"
  environment           = "dev"
  ec2_key_name          = "my-key"
  ssl_cert_external     = "*.domain.name"
  ssl_cert_internal     = "*.domain.name"
  ssl_cert_admin        = "*.domain.name"
  ssl_cert_manager      = "*.domain.name"
  ssl_cert_portal       = "*.domain.name"

  tags = {
     Owner = "[email protected]"
     Team = "DevOps"
  }
}

Create the resources in AWS:

terraform init
terraform plan -out kong.plan
terraform apply kong.plan

If installing Enterprise Edition, while resources are being provisioned login to the AWS console and navigate to:

Systems Manager -> Parameter Store

Update the license key by editing the parameter (default value is "placeholder"):

/[service]/[environment]/ee/license

Alternatively, if your terraform files and state are secure, you can pass them as variables to the module for a completely hands-off installation.

To login to the EC2 instance(s):

ssh -i [/path/to/key/specified/in/ec2_key_name] ubuntu@[ec2-instance]

You are now ready to manage APIs!