Building the Gateway with Custom Policies¶
Install the AP CLI Tool¶
The ap CLI tool is used to build a custom gateway image with your own policies. Download the binary for your platform from the ap CLI v0.9.1 release page and follow the steps below to install it.
Step 1: Extract the binary
After downloading the zip file for your platform, extract it:
Extracting the archive creates a folder of the same name that contains the ap binary.
Step 2: Move the binary to a bin directory
Step 3: Add to PATH
Add the following line to your ~/.zshrc or ~/.bashrc:
Step 4: Reload your shell
Step 5: Verify the installation
Step 1: Extract the binary
After downloading the zip file, right-click it and select Extract All, or run in PowerShell:
Extracting the archive creates a folder of the same name that contains ap.exe.
Step 2: Move the binary to a bin directory
New-Item -ItemType Directory -Force -Path "$HOME\bin"
Move-Item ap-windows-<arch>-v0.9.1\ap.exe "$HOME\bin\ap.exe"
Step 3: Add to PATH
Run the following in PowerShell to permanently add ~/bin to your user PATH:
Step 4: Reload your shell
Close and reopen PowerShell for the PATH change to take effect.
Step 5: Verify the installation
Configure the Build File¶
The build.yaml file is already included in the unzipped gateway package. It declares the gateway version and the list of policies to include. Edit this file to add your custom policies before building the gateway image.
Sample Custom Policies
WSO2 provides a set of sample custom policies to help you get started. You can find them in the api-platform sample policies repository.
Structure¶
version: v1
gateway:
version: 2026.10.0
policies:
- name: <policy-name>
gomodule: <go-module-path>@<version> # for policy hub managed policies
- name: <custom-policy-name>
filePath: <relative-path-to-policy-dir> # for custom policies
Each policy entry uses one of two source types:
| Field | Description |
|---|---|
gomodule |
Go module reference for policy hub managed policies (e.g., github.com/wso2/gateway-controllers/policies/cors@v1) |
filePath |
Relative path from build.yaml to a local custom policy directory |
Adding a Custom Policy¶
Your custom policy can reside anywhere on the filesystem. Use a relative path from the build.yaml file to point to it.
For example, if your directory layout is:
my-gateway/
├── build.yaml
└── ../my-custom-policy/ # policy lives outside the gateway directory
├── policy-definition.yaml
└── mypolicy.go
Add the policy to build.yaml using a relative filePath:
Note
The path in filePath is always relative to the location of build.yaml, not the directory from which you run the ap command.
Overriding the Base Images¶
ap gateway image build resolves three images during a build: the builder image that performs the build, and the controller and runtime base images that the produced images extend. In the gateway package, build.yaml already sets all three to the WSO2 private registry (registry.wso2.com):
version: v1
gateway:
version: 2026.10.0
images:
builder: registry.wso2.com/wso2-api-platform/sts/gateway-builder:2026.10.0
controller: registry.wso2.com/wso2-api-platform/sts/gateway-controller:2026.10.0
runtime: registry.wso2.com/wso2-api-platform/sts/gateway-runtime:2026.10.0
policies:
- name: set-headers
gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1
Keep the images block when you edit build.yaml. You can point any of the three keys at another registry, such as an internal mirror. The resolved images are printed at the start of the build under Resolved images, so you can confirm which ones were used.
The ap CLI uses your local Docker installation to pull and build images, so log in to the WSO2 private registry with your WSO2 subscription credentials first:
Build the Gateway Image¶
Once build.yaml is ready, run the following command from the directory containing build.yaml to build the custom gateway image:
This packages the gateway runtime together with all listed policies into a container image that can be used in place of the standard gateway image.
Once the build completes, the output lists the two image names produced. For example:
✓ Built gateway images with 1 policies:
• registry.wso2.com/wso2-api-platform/sts/my-gateway-gateway-runtime:2026.10.0
• registry.wso2.com/wso2-api-platform/sts/my-gateway-gateway-controller:2026.10.0
A build-manifest.yaml file is also written alongside build.yaml, recording the resolved versions of all policies included in the build.
Update the Docker Compose File¶
After building, update the image: fields in your docker-compose.yaml to use the newly built images.
Locate the gateway-controller and gateway-runtime services and replace their image: values with the images from the build output:
services:
gateway-controller:
image: registry.wso2.com/wso2-api-platform/sts/my-gateway-gateway-controller:2026.10.0 # (1)
gateway-runtime:
image: registry.wso2.com/wso2-api-platform/sts/my-gateway-gateway-runtime:2026.10.0 # (2)
- Replace with the
gateway-controllerimage name from your build output. - Replace with the
gateway-runtimeimage name from your build output.
Once updated, start the gateway as usual:
Deploy the API¶
The management API uses basic auth. Export the admin credentials scripts/setup.sh provisioned (the
username defaults to admin; use the password it printed):
curl -X POST http://localhost:9090/api/management/v1/rest-apis \
-u "$ADMIN_USERNAME:$ADMIN_PASSWORD" \
-H "Content-Type: application/yaml" \
--data-binary @- <<'EOF'
apiVersion: gateway.api-platform.wso2.com/v1
kind: RestApi
metadata:
name: reading-list-api-v1.0
spec:
displayName: Reading-List-API
version: v1.0
context: /reading-list/$version
upstream:
main:
url: https://apis.bijira.dev/samples/reading-list-api-service/v1.0
policies:
- name: set-headers
version: v1
params:
request:
headers:
- name: x-wso2-apip-gateway-version
value: v1.0.0
response:
headers:
- name: x-environment
value: development
operations:
- method: GET
path: /books
- method: POST
path: /books
- method: GET
path: /books/{id}
- method: PUT
path: /books/{id}
- method: DELETE
path: /books/{id}
EOF