GitOps to Configure Kong: How to Set Up GitHub Actions Using decK
Kong’s fast, lightweight and scalable API management solution helps improve developer productivity by automating the delivery of API management. One way Kong automates API management is through a continuous integration and continuous delivery (CI/CD) process by leveraging Kong's decK (declarative configuration for Kong) and GitHub Actions.
Kong's decK provides a command line interface (CLI) to manage Kong in a declarative way. This allows organizations to manage their configuration in Git repositories, manage version control and leverage GitOps to automate the application of the configuration.
From a business perspective, establishing a CI/CD process accelerates innovation, increases quality and provides better customer satisfaction.
In this blog post, I will navigate through how to set up GitHub Action with decK to start GitOps for Kong. By the end of this post, we will be able to open a pull request (PR) in GitHub that will:
- Validate the configuration being applied via `deck validate` and list how the configuration will change via `deck diff`
- Apply the new configuration via `deck sync` when you merge the pull request
To accomplish these, we will set up two workflows - one on a pull request and the other on merge to master. The PR action will do `deck diff` and the merge to master will do `deck sync`, respectively.
Prerequisites
- Access to GitHub or GitHub Enterprise Server
- Access to GitHub Actions as part of your GitHub subscriptions
- Kong instance is already set up (this post assumes you're using Kong Enterprise, but the Kong Gateway open source version should work as well)
- Kong instance can be reached from GitHub Actions (if your instance is behind a corporate firewall, GitHub's self-hosted runner would be a good option)
- decK is installed
Preparation
In my case, I have an existing Kong environment; therefore, I will first export my existing configuration with deck dump.
Please make sure the `–kong-addr` option points to your Kong Admin API base url, and add the `–headers` option to embed your admin token if your Kong is configured with `rbac: on`. For Kong Enterprise users, the `–all-workspaces` will export all configurations from each workspace.
This command will return no output when successfully executed:
In my case, Kong has three workspaces, which are IT, LOB and default, as you can see below.
You have now successfully stored the files into a local gGit repository. Let's push them to GitHub by first creating a repo in GitHub, Choose either public or private for this post.
When you are creating a repo in GitHub, please make sure not to initialize README for the following step work.
After the repo is created, you will see the instructions below:
With the Github repository created, we can now add and push to it:
Now, you have successfully set up your Git repository for Kong configuration. You can see the yaml file(s) in GitHub like below:
Make sure to give this file permission to execute:
Now, we have successfully set up the action. Let's create a workflow file that runs the action.
Workflow files should be located under `.github/workflow/` directory.
Let's create the `.github/workflow/` directory as shown below:
Set Up Workflow on a Pull Request
First, we will set up the workflow on a pull request event that validates the configuration. Let's create `.github/workflows/CI.yaml` with your favorite editor, as shown below.
NOTE: I'm using a Kong Enterprise instance with RBAC enabled. If your instance has RBAC disabled, remove the `–headers ${{ secrets.KONG_HEADERS }}”` from the options section of each step in the workflow.
The workflow will execute four steps sequentially:
Next, let's push all the files we created to GitHub now.
After successfully pushing the latest changes to GitHub, the repository should look like this:
Let's now set the secrets that the action will use by going to the GitHub UI, Settings and Secrets section on the side panel.
Add a new secret for KONG_ADDR, and if RBAC is turned on in your Kong installation, add another secret for KONG_HEADERS, which contains "Kong-Admin-Token:***".
We're all set! Let's confirm the action on a pull request works.
Open a Pull Request to Trigger the Workflow
Next, I'll create a new branch, commit this change to the branch and push it to GitHub. Then I'll open a new pull request in the GitHub UI. If you are not familiar with how to open a pull request, please see: https://guides.github.com/activities/hello-world/.
After successfully opening a pull request, the GitHub Action should start running.
We can see the result of the action in the "Checks" tab in the pull request as shown below.
Reviewing the results of the Action, we should see the results of the decK commands. In particular, deck diff shows how the Kong configuration will change when the changes are merged.
To do this, please create another yaml file under `.github/workflows` directory. Let's call it "sync.yaml" like below:
With this action, when changes are pushed to the master branch or a pull request is merged to master, the `deck sync` command will run to apply the configuration to Kong.
After the workflow has successfully finished, we can verify the new configuration was successfully applied. Let's validate using Kong Manager.
Congratulations! We have successfully set up a CI/CD pipeline to manage the Kong configuration declaratively using GitHub Actions!
For your convenience, I've created a reusable GitHub Action for decK, which you can fork and modify for your environment: https://github.com/ikeike443/decK-action.
Conclusion
In this post, we configured how to set up GitHub Actions to configure Kong declaratively with GitOps using decK. If you have any questions, please feel free to contact me on GitHub.
Happy hacking!