Skip to content

Commit 00a1481

Browse files
baraka-akeylesscursoragent
baraka-akeyless
and
cursoragent
committed
feat: Kong Gateway Enterprise Akeyless vault backend v0.1.0
Native Secrets Management vault strategy for Akeyless (kong.vaults.akeyless), with Docker/decK examples, validation scripts, and Kong partner submission docs. Co-authored-by: Cursor <cursoragent@cursor.com>
0 parents  commit 00a1481

25 files changed

Lines changed: 1731 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
lint:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- name: Install tools
15+
run: sudo apt-get update && sudo apt-get install -y shellcheck lua5.1
16+
17+
- name: Lint
18+
run: make lint
19+
20+
preflight:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v4
24+
25+
- name: Preflight
26+
run: |
27+
cp examples/.env.example examples/.env
28+
./scripts/preflight.sh

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
examples/.env
2+
*.swp
3+
*.swo
4+
.DS_Store
5+
.luarocks/

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Changelog
2+
3+
## [0.1.0] - 2026-06-16
4+
5+
### Added
6+
7+
- Kong Gateway vault strategy (`kong.vaults.akeyless`) for Akeyless Secrets Manager
8+
- Auth methods: `api_key`, `token`, `kubernetes`, `aws_iam`, `azure_ad`, `gcp`, `universal_identity`
9+
- LuaRocks package spec for joint QA with Kong engineering
10+
- Docker Compose demo, decK example, validation scripts
11+
- Kong-format how-to and partner submission playbook

‎LICENSE‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
2+
Apache License
3+
Version 2.0, January 2004
4+
http://www.apache.org/licenses/
5+
6+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7+
8+
Copyright 2026 Akeyless Community Contributors
9+
10+
Licensed under the Apache License, Version 2.0 (the "License");
11+
you may not use this file except in compliance with the License.
12+
You may obtain a copy of the License at
13+
14+
http://www.apache.org/licenses/LICENSE-2.0
15+
16+
Unless required by applicable law or agreed to in writing, software
17+
distributed under the License is distributed on an "AS IS" BASIS,
18+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19+
See the License for the specific language governing permissions and
20+
limitations under the License.

‎Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.PHONY: help preflight test-api lint validate
2+
3+
help:
4+
@echo "Targets:"
5+
@echo " make preflight - check local dependencies"
6+
@echo " make test-api - smoke test Akeyless API (requires examples/.env)"
7+
@echo " make lint - shellcheck + luac syntax check"
8+
@echo " make validate - full validation (API + Kong if running)"
9+
10+
preflight:
11+
@./scripts/preflight.sh
12+
13+
test-api:
14+
@./scripts/test-akeyless-api.sh
15+
16+
lint:
17+
@./scripts/lint.sh
18+
19+
validate:
20+
@./scripts/validate-vault.sh

‎README.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Kong Gateway Akeyless Vault Backend
2+
3+
Native [Kong Gateway](https://konghq.com) Secrets Management integration for [Akeyless](https://www.akeyless.io). Resolve `{vault://...}` references in `kong.conf`, declarative config, plugin fields, and certificates — without storing plaintext secrets in Kong.
4+
5+
**Target listing:** [Kong Supported Vault backends](https://developer.konghq.com/gateway/entities/vault/#supported-vault-backends) (same category as HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, and CyberArk Conjur).
6+
7+
> **Ready for Kong partner review.** See **[docs/YOUR-ACTION-CHECKLIST.md](docs/YOUR-ACTION-CHECKLIST.md)** for what to do next (publish repo, validate, contact Kong).
8+
9+
## What this provides
10+
11+
| Component | Description |
12+
|-----------|-------------|
13+
| **Vault strategy** | Lua module (`kong.vaults.akeyless`) implementing Kong's vault `get(conf, resource, version)` contract |
14+
| **LuaRocks package** | Install into Kong Gateway Enterprise for joint QA before native bundling |
15+
| **decK examples** | Declarative Vault entity + plugin secret references |
16+
| **Docker Compose demo** | Kong Gateway + PostgreSQL with mounted vault strategy |
17+
| **Kong-format docs** | Draft how-to for developer.konghq.com |
18+
| **Partner playbook** | Steps to land on Kong's official vault backends page |
19+
20+
## How it works
21+
22+
```
23+
┌─────────────────┐ {vault://akeyless-vault/demo/api-key} ┌──────────────┐
24+
│ Kong Gateway │ ──────────────────────────────────────────────► │ Akeyless │
25+
│ (Enterprise) │ POST /auth → POST /get-secret-value │ SaaS / GW │
26+
└─────────────────┘ └──────────────┘
27+
```
28+
29+
1. Create a **Vault entity** with `name: akeyless` and your gateway credentials.
30+
2. Store secrets in Akeyless under a path prefix (e.g. `/kong/...`).
31+
3. Reference secrets anywhere Kong supports vault references.
32+
33+
### Example references
34+
35+
| Akeyless path | `path_prefix` | Kong reference |
36+
|---------------|---------------|----------------|
37+
| `/kong/demo/api-key` | `/kong` | `{vault://akeyless-vault/demo/api-key}` |
38+
| `/kong/pg` (JSON `username`/`password`) | `/kong` | `{vault://akeyless-vault/pg/username}` |
39+
40+
## Quick start
41+
42+
### 1. Prerequisites
43+
44+
- Kong Gateway **Enterprise** license
45+
- Akeyless Access ID + Access Key (or Kubernetes / cloud IAM auth)
46+
- [decK](https://developer.konghq.com/deck/) (optional)
47+
- Docker (for local demo)
48+
49+
### 2. Create a demo secret in Akeyless
50+
51+
```bash
52+
cp examples/.env.example examples/.env
53+
# Edit examples/.env with your credentials
54+
55+
./scripts/setup-demo-secrets.sh # requires Akeyless CLI
56+
```
57+
58+
Or create `/kong/demo/api-key` manually in the Akeyless console.
59+
60+
### 3. Test Akeyless API (no Kong)
61+
62+
```bash
63+
./scripts/test-akeyless-api.sh
64+
```
65+
66+
### 4. Run Kong demo stack
67+
68+
```bash
69+
export KONG_LICENSE_DATA='...' # or add to examples/.env
70+
docker compose -f examples/docker-compose.yml up -d
71+
```
72+
73+
### 5. Apply Vault entity and validate
74+
75+
```bash
76+
export DECK_AKEYLESS_GATEWAY_URL=https://api.akeyless.io
77+
export DECK_AKEYLESS_ACCESS_ID=p-xxxxx
78+
export DECK_AKEYLESS_ACCESS_KEY=...
79+
80+
deck gateway apply examples/kong.yaml
81+
82+
docker compose -f examples/docker-compose.yml exec kong-gateway \
83+
kong vault get '{vault://akeyless-vault/demo/api-key}'
84+
```
85+
86+
Or run the full validation script:
87+
88+
```bash
89+
./scripts/validate-vault.sh
90+
```
91+
92+
## Install vault strategy
93+
94+
Until Kong bundles Akeyless natively:
95+
96+
**Option A — mount files (demo)**
97+
98+
```yaml
99+
volumes:
100+
- ./vault-strategy/kong/vaults/akeyless:/usr/local/share/lua/5.1/kong/vaults/akeyless:ro
101+
```
102+
103+
**Option B — LuaRocks**
104+
105+
```bash
106+
luarocks make kong-vault-akeyless-0.1.0-1.rockspec
107+
```
108+
109+
## Configuration
110+
111+
### Vault entity (decK / Admin API)
112+
113+
```yaml
114+
vaults:
115+
- name: akeyless
116+
prefix: akeyless-vault
117+
config:
118+
gateway_url: "https://api.akeyless.io"
119+
auth_method: api_key
120+
access_id: "p-xxxxxxxx"
121+
access_key: "your-access-key"
122+
path_prefix: "/kong"
123+
ttl: 60
124+
```
125+
126+
### Authentication methods
127+
128+
| Method | Fields | Notes |
129+
|--------|--------|-------|
130+
| `api_key` | `access_id`, `access_key` | Default |
131+
| `token` | `token` | Skip `/auth` |
132+
| `kubernetes` | `access_id`, `k8s_auth_config_name` | Reads SA token from file |
133+
| `aws_iam` | `access_id` | EC2/EKS instance metadata |
134+
| `azure_ad` | `access_id` | Azure IMDS |
135+
| `gcp` | `access_id`, `gcp_audience` | GCE/GKE metadata |
136+
| `universal_identity` | `uid_token` | Universal Identity |
137+
138+
See [docs/configure-akeyless-as-vault-backend.md](docs/configure-akeyless-as-vault-backend.md) for the full parameter table.
139+
140+
## Appearing on developer.konghq.com
141+
142+
Native listing requires Kong to **bundle** the vault strategy in Gateway Enterprise (not a community plugin).
143+
144+
| Doc | Purpose |
145+
|-----|---------|
146+
| [YOUR-ACTION-CHECKLIST.md](docs/YOUR-ACTION-CHECKLIST.md) | **Start here** — your to-do list |
147+
| [publish-to-github.md](docs/publish-to-github.md) | Push to `akeyless-community` |
148+
| [partner-outreach-email.md](docs/partner-outreach-email.md) | Copy/paste Kong email |
149+
| [kong-engineering-handoff.md](docs/kong-engineering-handoff.md) | One-pager for Kong engineers |
150+
| [kong-partner-submission.md](docs/kong-partner-submission.md) | Full partner playbook |
151+
152+
## Repository layout
153+
154+
```
155+
kong-akeyless-integration/
156+
├── vault-strategy/kong/vaults/akeyless/ # Lua vault backend
157+
├── kong-vault-akeyless-0.1.0-1.rockspec # LuaRocks (repo root)
158+
├── examples/ # docker-compose, kong.yaml, .env
159+
├── scripts/ # validate, setup, API smoke test
160+
├── .github/workflows/ci.yml # lint + preflight
161+
└── docs/ # how-to, partner email, your checklist
162+
```
163+
164+
## Security notes
165+
166+
- Scope Akeyless auth to `/kong/*` (or your prefix) with read-only access.
167+
- Use Kubernetes or cloud IAM auth on Kong data planes when possible instead of long-lived access keys.
168+
- Kong never logs resolved secret values when vault references are used correctly.
169+
170+
## Related projects
171+
172+
- [Jenkins Akeyless Credentials Provider](../JenkinsSecretsManagerProvider)
173+
- [Buildkite Akeyless Plugin](../buildkite-akeyless-plugin)
174+
- [Octopus Deploy Akeyless Step Templates](../octopus-akeyless-plugin)
175+
176+
## License
177+
178+
Apache-2.0

‎SECURITY.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Security Policy
2+
3+
## Supported versions
4+
5+
| Version | Supported |
6+
|---------|-----------|
7+
| 0.1.x | Yes |
8+
9+
## Reporting a vulnerability
10+
11+
Do **not** open a public GitHub issue for security vulnerabilities.
12+
13+
Email **security@akeyless.io** with:
14+
15+
- Description of the issue
16+
- Steps to reproduce
17+
- Impact assessment (if known)
18+
19+
For Kong Gateway Enterprise deployments, also notify your Kong support channel if the issue affects bundled code after merge.
20+
21+
## Integration security guidance
22+
23+
- Scope Akeyless auth methods to the minimum path prefix (e.g. `/kong/*`) with **read-only** access.
24+
- Prefer Kubernetes or cloud IAM auth on Kong data planes over long-lived API keys.
25+
- Never commit `examples/.env` or Kong license data to version control.
26+
- Rotate Akeyless access keys if they are ever exposed in logs or CI output.

‎docs/YOUR-ACTION-CHECKLIST.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Your action checklist
2+
3+
Everything the agent prepared is in `kong-akeyless-integration/`. These steps require **you** (Akeyless team) — credentials, GitHub org access, and Kong partner outreach.
4+
5+
## Phase 1 — Publish the repo (today)
6+
7+
- [ ] **Create public repo** `github.com/akeyless-community/kong-akeyless-integration`
8+
- [ ] **Push this folder** as the initial commit (see [publish-to-github.md](publish-to-github.md))
9+
- [ ] Set repo description: `Native Kong Gateway Enterprise vault backend for Akeyless Secrets Management`
10+
- [ ] Add topics: `kong`, `kong-gateway`, `akeyless`, `secrets-management`, `vault`
11+
- [ ] Tag release: `git tag v0.1.0 && git push origin v0.1.0`
12+
- [ ] Enable GitHub Issues (for Kong engineering questions)
13+
14+
## Phase 2 — Validate locally (before contacting Kong)
15+
16+
- [ ] Copy `examples/.env.example` → `examples/.env`
17+
- [ ] Fill in:
18+
- `AKEYLESS_ACCESS_ID` / `AKEYLESS_ACCESS_KEY`
19+
- `KONG_LICENSE_DATA` (Enterprise trial or existing license)
20+
- [ ] Run:
21+
22+
```bash
23+
cd kong-akeyless-integration
24+
make preflight
25+
./scripts/setup-demo-secrets.sh # or create /kong/demo/api-key in console
26+
make test-api # Akeyless API only
27+
docker compose -f examples/docker-compose.yml up -d
28+
deck gateway apply examples/kong.yaml
29+
make validate
30+
```
31+
32+
- [ ] Save terminal output from `make validate` — attach to partner email as proof
33+
34+
## Phase 3 — Kong partner outreach (same week as publish)
35+
36+
- [ ] **Apply:** https://konghq.com/partners/become-a-partner
37+
- Category: Technology integration
38+
- Product: Kong Gateway Enterprise Secrets Management (native vault backend)
39+
- [ ] **Email** Kong using [partner-outreach-email.md](partner-outreach-email.md)
40+
- To: your Kong AE / partner manager (if you have one)
41+
- Cc: Akeyless alliances / BD contact
42+
- [ ] **Attach / link:**
43+
- Repo URL
44+
- [kong-engineering-handoff.md](kong-engineering-handoff.md)
45+
- `validate-vault.sh` success output
46+
- [ ] **Prepare for Kong QA** (fill in handoff doc):
47+
- Dedicated test Access ID scoped to `/kong/*` read-only
48+
- Named engineering contact + calendar link
49+
50+
## Phase 4 — After Kong responds
51+
52+
- [ ] Joint call with Kong Gateway / Secrets Management engineering
53+
- [ ] Address review feedback on `init.lua` / `schema.lua`
54+
- [ ] Kong merges into Enterprise + publishes docs
55+
- [ ] Confirm listing on https://developer.konghq.com/gateway/entities/vault/#supported-vault-backends
56+
- [ ] Cross-link from Akeyless docs
57+
- [ ] Optional: joint blog post
58+
59+
## What you do NOT need to do
60+
61+
| Action | Why skip |
62+
|--------|----------|
63+
| Open PR to `Kong/kong` (OSS) | Enterprise vaults are bundled separately |
64+
| Submit to Kong Hub as plugin | Vault backends are core Enterprise, not plugins |
65+
| Wait for email reply before publishing repo | Repo should be live **before** outreach |
66+
67+
## Files ready for Kong
68+
69+
| File | Purpose |
70+
|------|---------|
71+
| `vault-strategy/kong/vaults/akeyless/init.lua` | Integration code |
72+
| `vault-strategy/kong/vaults/akeyless/schema.lua` | Config schema |
73+
| `docs/configure-akeyless-as-vault-backend.md` | Draft Kong docs page |
74+
| `docs/kong-engineering-handoff.md` | One-pager for engineers |
75+
| `docs/partner-outreach-email.md` | Copy/paste email |
76+
| `examples/docker-compose.yml` | Reproducible demo |
77+
| `scripts/validate-vault.sh` | E2E proof |
78+
79+
## Questions?
80+
81+
Open an issue in the published repo or contact your Akeyless integrations lead.

0 commit comments

Comments
 (0)