Skip to content

Commit a42180b

Browse files
renuka-fernandorenuka-fernando
authored
Merge pull request #1812 from wso2/python-policy-engine
Add policy languages and runtimes doc
2 parents 3438cd8 + fd798a0 commit a42180b

2 files changed

Lines changed: 191 additions & 0 deletions

File tree

‎docs/gateway/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,4 +70,5 @@ You can extend the gateway with your own policies or include specific policies f
7070
| [Analytics](analytics/) | Analytics integrations (Moesif) |
7171
| [REST APIs](../rest-apis/gateway/) | REST API authentication and usage |
7272
| [Policies and Guardrails](https://github.com/wso2/gateway-controllers/blob/main/docs/README.md) | Gateway policies and guardrails for API traffic control |
73+
| [Policy Languages and Runtimes](policy-languages-and-runtimes.md) | Dual-language policy development guide (Go and Python) |
7374
| [Immutable Gateway](immutable-gateway.md) | File-based, GitOps-native gateway configuration |

‎docs/gateway/policy-languages-and-runtimes.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Policy Languages and Runtimes
2+
3+
## Overview
4+
5+
The API Platform Gateway uses a **policy-based architecture** to intercept and transform API traffic flowing through the data plane. Policies are self-contained units of logic that run inside the Gateway Runtime, with the ability to inspect and modify requests, responses, headers, and body content at each stage of the processing pipeline.
6+
7+
The gateway supports **two languages** for authoring policies:
8+
9+
| Language | Runtime | Best For |
10+
|----------|---------|----------|
11+
| **Go** (default) | Compiled into the Policy Engine binary | Standard API policies — authentication, rate limiting, header manipulation, guardrails |
12+
| **Python** (beta) | Executed by the Python Executor | AI/ML workloads, prompt engineering, complex data transformations, and scenarios that benefit from Python's rich ecosystem |
13+
14+
Go is the **primary and recommended language** for policy development. It provides maximum execution performance, strict type safety, and minimal per-request latency. Python is available as a **specialized runtime** for use cases where access to Python-native libraries (NLP toolkits, compression engines, ML inference clients, etc.) outweighs the overhead of cross-process communication.
15+
16+
## How Policies Execute
17+
18+
Understanding where each language fits requires a brief look at the Gateway Runtime architecture:
19+
20+
```
21+
┌──────────────────────────────────────┐
22+
│ Gateway Runtime │
23+
Incoming │ │
24+
Request ────────► │ ┌────────┐ ┌──────────────┐ │ Upstream
25+
│ │ Router │─────►│ Policy Engine│────┼────► Backend
26+
Response ◄──────── │ │(Envoy) │◄─────│ (Go) │ │
27+
│ └────────┘ └──────┬───────┘ │
28+
│ │ gRPC/UDS │
29+
│ ┌──────▼───────┐ │
30+
│ │ Python │ │
31+
│ │ Executor │ │
32+
│ └──────────────┘ │
33+
└──────────────────────────────────────┘
34+
```
35+
36+
- **Go policies** are compiled directly into the **Policy Engine** binary at image build time. When the Router hands off a request to the Policy Engine via the `ext_proc` filter, Go policies execute in-process with zero serialization overhead.
37+
38+
- **Python policies** run in a dedicated **Python Executor** process. The Go Policy Engine delegates execution to the Python Executor over a local gRPC connection using a Unix Domain Socket. The executor manages policy lifecycle — loading, initialization, execution, and teardown in an isolated Python runtime.
39+
40+
> **Note:** Both Go and Python policies share the same policy evaluation pipeline. From the perspective of API configuration and deployment, a policy's language is transparent — you attach Go and Python policies to APIs in exactly the same way.
41+
42+
## Policy Anatomy
43+
44+
Regardless of language, every policy consists of two parts:
45+
46+
## 1. Policy Definition (`policy-definition.yaml`)
47+
48+
A declarative YAML file that describes the policy's identity, version, and configuration schema. This file is the same for both Go and Python policies.
49+
50+
```yaml
51+
name: my-policy
52+
version: v1.0.0
53+
displayName: My Policy
54+
description: |
55+
A short description of what this policy does.
56+
57+
parameters:
58+
type: object
59+
properties:
60+
myParam:
61+
type: string
62+
description: "An example parameter."
63+
default: "hello"
64+
required:
65+
- myParam
66+
67+
systemParameters:
68+
type: object
69+
additionalProperties: false
70+
properties: {}
71+
```
72+
73+
| Field | Purpose |
74+
|-------|---------|
75+
| `name` | Unique policy identifier, used in API definitions to reference the policy |
76+
| `version` | Semantic version (e.g., `v1.0.0`). The major version is used as the policy version qualifier |
77+
| `parameters` | JSON Schema describing the user-configurable parameters for the policy |
78+
| `systemParameters` | JSON Schema for operator-level configuration (set via gateway config, not per-API) |
79+
80+
## 2. Policy Implementation
81+
82+
The implementation is where the two languages diverge.
83+
84+
### 2.1. Go Policies
85+
86+
Go is the **default and recommended** language for policy development. Every built-in policy that ships with the gateway — authentication, rate limiting, CORS, guardrails, header manipulation — is written in Go.
87+
88+
### Why Go?
89+
90+
- **Performance:** Compiled into the Policy Engine binary. No serialization, no IPC, no interpreter overhead.
91+
- **Type safety:** Compile-time guarantees reduce runtime errors in production.
92+
- **Ecosystem alignment:** The Policy Engine, Gateway Builder, and Gateway Controller are all Go codebases.
93+
- **Broad applicability:** Ideal for the vast majority of API management use cases.
94+
95+
### Go Policy Structure
96+
97+
A Go policy is a standard **Go module** containing the policy definition and the implementation:
98+
99+
```
100+
my-go-policy/
101+
├── policy-definition.yaml
102+
├── go.mod
103+
├── go.sum
104+
├── policy.go
105+
└── policy_test.go
106+
```
107+
108+
| File | Purpose |
109+
|------|---------|
110+
| `policy-definition.yaml` | Declares name, version, and parameter schema |
111+
| `go.mod` / `go.sum` | Go module definition and dependency lockfiles |
112+
| `policy.go` | Policy implementation |
113+
| `policy_test.go` | Unit tests for the policy logic |
114+
115+
Go policies implement interfaces from the gateway's Policy SDK. The Policy Engine loads them at build time via the `build.yaml` manifest.
116+
117+
### Build Integration
118+
119+
Go policies are referenced in `build.yaml` using the `gomodule` field, which points to the Go module path:
120+
121+
```yaml
122+
policies:
123+
- name: my-go-policy
124+
gomodule: github.com/wso2/gateway-controllers/policies/my-go-policy@v1
125+
```
126+
127+
The **Gateway Builder** resolves these modules, compiles them into the Policy Engine binary, and produces a custom gateway image containing all declared policies.
128+
129+
### 2.2. Python Policies (Beta)
130+
131+
Python policy support extends the gateway's capabilities into domains where Python's ecosystem is unmatched — particularly **AI/ML, natural language processing, and complex data transformations**.
132+
133+
### Why Python?
134+
135+
- **AI/ML ecosystem:** Direct access to libraries like `transformers`, `tiktoken`, `scikit-learn`, and custom compression engines.
136+
- **Rapid prototyping:** Faster iteration for experimental or research-oriented policies.
137+
- **Specialized use cases:** Prompt compression, semantic analysis, content classification, and other tasks where Python libraries provide capabilities that would be impractical to reimplement in Go.
138+
139+
### Python Policy Structure
140+
141+
Python policies follow the standard `src` layout and are packaged as installable Python packages:
142+
143+
```
144+
my-python-policy/
145+
├── policy-definition.yaml
146+
├── pyproject.toml
147+
├── requirements.txt
148+
├── src/
149+
│ └── my_python_policy_v1/
150+
│ ├── __init__.py
151+
│ └── policy.py
152+
└── tests/
153+
└── test_policy.py
154+
```
155+
156+
| File | Purpose |
157+
|------|---------|
158+
| `policy-definition.yaml` | Same format as Go — declares name, version, and parameter schema |
159+
| `pyproject.toml` | Standard Python packaging configuration. Uses `hatchling` as the build backend |
160+
| `requirements.txt` | Runtime dependencies |
161+
| `src/<package>/policy.py` | Policy implementation |
162+
| `tests/` | Unit tests for the policy logic |
163+
164+
### Build Integration
165+
166+
Python policies are referenced in `build.yaml` using the `pipPackage` field instead of `gomodule`:
167+
168+
```yaml
169+
policies:
170+
- name: my-python-policy
171+
pipPackage: github.com/wso2/gateway-controllers/policies/my-python-policy@v1
172+
```
173+
174+
The Gateway Builder resolves the Python package, installs its dependencies, generates the policy registry, and bundles everything into the gateway image alongside the Python Executor.
175+
176+
## Choosing a Language
177+
178+
Use this decision guide when planning a new policy:
179+
180+
| Consideration | Choose Go | Choose Python |
181+
|---------------|-----------|---------------|
182+
| **Performance-critical path** | ✅ In-process, zero overhead | ❌ Cross-process gRPC call |
183+
| **Standard API management** (auth, rate limiting, headers) | ✅ Existing patterns and SDK | Possible, but unnecessary |
184+
| **AI/ML or NLP processing** | Requires reimplementation of libraries | ✅ Direct access to Python ecosystem |
185+
| **Complex data transformations** | Good for structured transforms | ✅ Better for text/NLP transforms |
186+
| **Third-party library dependency** | Go library must exist | ✅ Vast PyPI ecosystem |
187+
| **Production stability** | ✅ Compiled, type-safe | Interpreted, requires thorough testing |
188+
| **Team expertise** | Go-proficient team | Python-proficient team |
189+
190+
Start with Go unless your policy specifically requires Python libraries or Python-native capabilities. The majority of gateway policies are written in Go.

0 commit comments

Comments
 (0)