May 4, 2021
4 min read

Kong Configurations Using Terraform via GitOps Model

Vaibhav Khurana

As organizations adopt a microservices architecture, API gateway usage has increased. Kong Gateway is one of the promising API gateways in the market. It has both OSS and enterprise support, releases multiple features and is easy to use.

Kong Admin API helps administrators configure the system easily, but it's still error-prone. That's because the user has to hit many curl calls for creating all the configs. When numerous folks are managing the system, this becomes difficult.

The simplistic approach to solving all these issues is to move all the configurations to the GitOps model. Then, move all the configs to a VCS repository and follow the PR model to apply all the changes to any environment. To do this, you must have:

  1. All the configurations present in VCS for easy consumption
  2. A PR approval mechanism in place to verify all the configurations
  3. A way to revert the commit and re-apply mistakes during reviews

Combining the benefits of GitOps and Terraform as IAC gives us the following advantages over the conventional manual curl calls:

  1. A state lock so that no two people make changes on the same objects
  2. Easy-to-identify changes introduced as part of the apply, making a more informed decision
  3. Using terraform apply to fix any mistakes

Demo: Kong Configs Using Terraform

For this demo, I'll be doing the following:

  1. Use a VCS repo to push the code that will create a service, route, upstream and the targets for this service.
  2. Apply the Kong configurations via Terraform.
  3. Make a change, analyze the diffs and apply the changes.


For making configurations more simple and easy to manage, I published a module in the Terraform Registry.

The code used in this demo is also there in the GitHub repo for reference.

Before moving ahead with the code, verify that your Kong Admin API is working and that you have this configuration:

Kong Configurations at Start

From the above picture, it is clear that Kong Admin API is accessible and has no configurations.


This file contains the state information, including the backend and the providers I will be using.

Note: Please replace the kong_admin_uri with the admin URI of your Kong Gateway.

Pro Tip: You should use remote backend storage like S3 for storing the state.


Create this file and use the below code for creating all the required resources.

This code is required for creating a service called base-svc, which will forward all the requests to the target base-svc.cluster.local:8001 for the requests matching route or

3. Run Terraform Init for initializing the backend and the provider.

Successful Terraform Init

If your Terraform provider configuration is correct, then you will get the above success message.

4. Run Terraform Plan for planning the changes done by the code.

Terraform Plan Output


If you have followed everything until now, you will get a similar output of the plan that will show you all the resources that are getting created.

5. Run Terraform Apply for applying all these configurations on Kong.

Successful Apply

6. Verify the changes via the Admin API curl calls:

Verified Creation of Service

Verified Creation of Route

Verified Creation-Upstream

7. Add a change in the code.

For example, I added another host header in the above configuration and planned again. The below shows that I added another host,, in my route config. The system will update it in place.

The module gives the flexibility of configuring all the required things by providing minimal information and code as well as the ability to do customizations on the default values from the callers, which is in the module's README.


In the demo above, I did the Terraform plan and applied it from my local machine. That might work for smaller teams, but that will not be something you'll want with a big team. For achieving a true GitOps model, you can use Atlantis for Terraform planning and apply it directly from the PR.

Plan via Atlantis


In this article, I configured a Kong Gateway service using the module with minimal code and no hassle by ensuring that all configurations exist in a VCS repo. This solved issues like audit, approvals, reverts, etc., thus helping me follow the GitOps model. Along with Atlantis, this gives me a way to make sure that all the changes to Kong configurations are on track, audited and have clear visibility on the changes made as part of a PR.

If you have any additional questions, post them on Kong Nation.

To stay in touch, join the Kong Community.

Once you've successfully set up Kong Configurations Using Terraform, you may find these other tutorials helpful: