ACL configuration with Kong Gateway
This example covers a common use case: as an API owner, you want to regulate access based on the type of request methods and consumer groups. Specifically, the goal is to allow consumers in the dev group to perform GET, POST, and PUT requests on all routes, while reserving the DELETE request functionality exclusively for consumers in the admin group.
Create consumers
Using the API, create two consumers, admin
and dev
.
- Create consumer
admin
:
curl -i -X POST http://localhost:8001/consumers \
--data "username=admin"
- Create consumer
dev
:
curl -i -X POST http://localhost:8001/consumers \
--data "username=dev"
The response for each request contains a UUID in the id
field that you will need for the rest of the guide.
Create consumer groups
- Using the API, create a consumer group for
dev
:
curl -i -X POST http://localhost:8001/consumer_groups \
--data "name=dev"
-
Then create a consumer group for admin
:
curl -i -X POST http://localhost:8001/consumer_groups \
--data "name=admin"
-
Add a consumer to the admin
group by using the UUID of the specific consumer:
curl -i -X POST http://localhost:8001/consumer_groups/admin/consumers \
--data "consumer=8a4bba3c-7f82-45f0-8121-ed4d2847c4a4"
-
Add a different consumer to the dev
group:
curl -i -X POST http://localhost:8001/consumer_groups/dev/consumers \
--data "consumer=8a4bba3c-7f82-45f0-8121-ed4d2847c4a4"
Create routes
Using the Admin API and the expressions router, create two routes: one that matches GET
, POST
and PUT
, and one that only matches DELETE
.
-
Create a route that matches when the method is not DELETE
:
curl --request POST \
--url http://localhost:8001/services/example-service/routes \
--form-string name=devs-and-admins \
--form-string expression='http.path == "/example" && http.method != "DELETE"'
-
Create a route that matches when the method is DELETE:
curl --request POST \
--url http://localhost:8001/services/example-service/routes \
--form-string name=only-admins \
--form-string expression='http.path == "/example" && http.method == "DELETE"'
Set up the ACL plugin
Scope the plugin to each of these routes with the respective allow
configuration.
Enable the ACL plugin on the devs-and-admin
route, setting the allow
field to accept both groups:
Kong Admin API
Konnect API
Kubernetes
Declarative (YAML)
Konnect Terraform
Make the following request:
curl -X POST http://localhost:8001/routes/{routeName|Id}/plugins \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
"name": "acl",
"config": {
"include_consumer_groups": true,
"allow": [
"dev",
"admin"
]
}
}
'
Replace ROUTE_NAME|ID
with the id
or name
of the route that this plugin configuration will target.
Make the following request, substituting your own access token, region, control plane ID, and route ID:
curl -X POST \
https://{us|eu}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/routes/{routeId}/plugins \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer TOKEN" \
--data '{"name":"acl","config":{"include_consumer_groups":true,"allow":["dev","admin"]}}'
See the Konnect API reference to learn about region-specific URLs and personal access tokens.
First, create a KongPlugin
resource:
echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: acl-example
plugin: acl
config:
include_consumer_groups: true
allow:
- dev
- admin
" | kubectl apply -f -
Next, apply the KongPlugin
resource to an ingress by annotating the ingress
as follows:
kubectl annotate ingress INGRESS_NAME konghq.com/plugins=acl-example
Replace INGRESS_NAME
with the name of the ingress that this plugin configuration will target.
You can see your available ingresses by running kubectl get ingress
.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: acl
route: ROUTE_NAME|ID
config:
include_consumer_groups: true
allow:
- dev
- admin
Replace ROUTE_NAME|ID
with the id
or name
of the route that this plugin configuration
will target.
Prerequisite: Configure your Personal Access Token
terraform {
required_providers {
konnect = {
source = "kong/konnect"
}
}
}
provider "konnect" {
personal_access_token = "kpat_YOUR_TOKEN"
server_url = "https://us.api.konghq.com/"
}
Add the following to your Terraform configuration to create a Konnect Gateway Plugin:
resource "konnect_gateway_plugin_acl" "my_acl" {
enabled = true
config = {
include_consumer_groups = true
allow = ["dev", "admin"]
}
control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
route = {
id = konnect_gateway_route.my_route.id
}
}
Enable another ACL plugin instance on the only-admins
route, setting the allow
field set to only accept the admin
group:
Kong Admin API
Konnect API
Kubernetes
Declarative (YAML)
Konnect Terraform
Make the following request:
curl -X POST http://localhost:8001/routes/{routeName|Id}/plugins \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
"name": "acl",
"config": {
"include_consumer_groups": true,
"allow": [
"admin"
]
}
}
'
Replace ROUTE_NAME|ID
with the id
or name
of the route that this plugin configuration will target.
Make the following request, substituting your own access token, region, control plane ID, and route ID:
curl -X POST \
https://{us|eu}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/routes/{routeId}/plugins \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer TOKEN" \
--data '{"name":"acl","config":{"include_consumer_groups":true,"allow":["admin"]}}'
See the Konnect API reference to learn about region-specific URLs and personal access tokens.
First, create a KongPlugin
resource:
echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: acl-example
plugin: acl
config:
include_consumer_groups: true
allow:
- admin
" | kubectl apply -f -
Next, apply the KongPlugin
resource to an ingress by annotating the ingress
as follows:
kubectl annotate ingress INGRESS_NAME konghq.com/plugins=acl-example
Replace INGRESS_NAME
with the name of the ingress that this plugin configuration will target.
You can see your available ingresses by running kubectl get ingress
.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: acl
route: ROUTE_NAME|ID
config:
include_consumer_groups: true
allow:
- admin
Replace ROUTE_NAME|ID
with the id
or name
of the route that this plugin configuration
will target.
Prerequisite: Configure your Personal Access Token
terraform {
required_providers {
konnect = {
source = "kong/konnect"
}
}
}
provider "konnect" {
personal_access_token = "kpat_YOUR_TOKEN"
server_url = "https://us.api.konghq.com/"
}
Add the following to your Terraform configuration to create a Konnect Gateway Plugin:
resource "konnect_gateway_plugin_acl" "my_acl" {
enabled = true
config = {
include_consumer_groups = true
allow = ["admin"]
}
control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
route = {
id = konnect_gateway_route.my_route.id
}
}