diff --git a/en/docs/ai-gateway/1.0.0/overview.md b/en/docs/ai-gateway/1.0.0/overview.md index 96d48e0403..1002c3ccc6 100644 --- a/en/docs/ai-gateway/1.0.0/overview.md +++ b/en/docs/ai-gateway/1.0.0/overview.md @@ -103,7 +103,7 @@ AI Guardrails allow you to enforce safety, content, and compliance policies on A The complete and up-to-date guardrail catalogue — with configuration references and examples — is maintained in the gateway-controllers repository: [https://github.com/wso2/gateway-controllers/blob/main/docs/README.md](https://github.com/wso2/gateway-controllers/blob/main/docs/README.md) -You can extend the AI Gateway with custom guardrail policies by building a custom gateway image using the `ap` CLI. See [Customizing the Gateway by Adding and Removing Policies](../../tools/cli/customizing-gateway-policies.md). +A guardrail is a gateway policy. To add a guardrail to the gateway, or update one to a different version, build a custom gateway image with the `ap` CLI and see [Add or Update Policies in a Gateway](../../api-gateway/1.0.0/policies/add-or-update-policies.md). To write your own guardrail policy, see [Writing a Custom Policy](../../api-gateway/1.0.0/policies/custom-policies/writing-a-custom-policy.md). ## Documentation diff --git a/en/docs/ai-gateway/1.1.0/overview.md b/en/docs/ai-gateway/1.1.0/overview.md index 33665af5f5..63a3172c21 100644 --- a/en/docs/ai-gateway/1.1.0/overview.md +++ b/en/docs/ai-gateway/1.1.0/overview.md @@ -111,7 +111,7 @@ AI Guardrails allow you to enforce safety, content, and compliance policies on A The complete and up-to-date guardrail catalogue — with configuration references and examples — is maintained in the gateway-controllers repository: [https://github.com/wso2/gateway-controllers/blob/main/docs/README.md](https://github.com/wso2/gateway-controllers/blob/main/docs/README.md) -You can extend the AI Gateway with custom guardrail policies by building a custom gateway image using the `ap` CLI. See [Customizing the Gateway by Adding and Removing Policies](../../tools/cli/customizing-gateway-policies.md). +A guardrail is a gateway policy. To add a guardrail to the gateway, or update one to a different version, build a custom gateway image with the `ap` CLI and see [Add or Update Policies in a Gateway](../../api-gateway/1.1.0/policies/add-or-update-policies.md). To write your own guardrail policy, see [Writing a Custom Policy](../../api-gateway/1.1.0/policies/custom-policies/writing-a-custom-policy.md). ## Documentation diff --git a/en/docs/ai-gateway/1.2.0/guardrails/guardrails-catalogue.md b/en/docs/ai-gateway/1.2.0/guardrails/guardrails-catalogue.md index 45726df3af..2b43a9f9ba 100644 --- a/en/docs/ai-gateway/1.2.0/guardrails/guardrails-catalogue.md +++ b/en/docs/ai-gateway/1.2.0/guardrails/guardrails-catalogue.md @@ -36,9 +36,13 @@ Guardrail policies are documented in the [Policy Hub](https://wso2.com/api-platf | [Granite Guardian Prompt Injection](https://wso2.com/api-platform/policy-hub/policies/granite-guardian-prompt-injection) | Detects prompt injection and jailbreak attempts in LLM API requests using IBM Granite Guardian 3.3 8B | | [NeMo Guard Content Safety](https://wso2.com/api-platform/policy-hub/policies/nvidia-nemoguard-content-safety) | Validates request and/or response content using NVIDIA NeMo Guard (llama-3.1-nemoguard-8b-content-safety) | +## Add or update guardrails + +A guardrail is a gateway policy, so you add or update one by editing the gateway's `build.yaml` and rebuilding the image with the `ap` CLI. See [Add or Update Policies in a Gateway](../../../api-gateway/1.2.0/policies/add-or-update-policies.md). + ## Custom guardrails -You can extend the AI Gateway with custom guardrail policies by building a custom gateway image using the `ap` CLI. See [Customizing the Gateway by Adding and Removing Policies](../../../tools/cli/customizing-gateway-policies.md). +To write your own guardrail policy in Go and build it into the gateway image, see [Writing a Custom Policy](../../../api-gateway/1.2.0/policies/custom-policies/writing-a-custom-policy.md). ## Related topics diff --git a/en/docs/ai-gateway/next/guardrails/guardrails-catalogue.md b/en/docs/ai-gateway/next/guardrails/guardrails-catalogue.md index 45726df3af..bfe50d2e3b 100644 --- a/en/docs/ai-gateway/next/guardrails/guardrails-catalogue.md +++ b/en/docs/ai-gateway/next/guardrails/guardrails-catalogue.md @@ -36,9 +36,13 @@ Guardrail policies are documented in the [Policy Hub](https://wso2.com/api-platf | [Granite Guardian Prompt Injection](https://wso2.com/api-platform/policy-hub/policies/granite-guardian-prompt-injection) | Detects prompt injection and jailbreak attempts in LLM API requests using IBM Granite Guardian 3.3 8B | | [NeMo Guard Content Safety](https://wso2.com/api-platform/policy-hub/policies/nvidia-nemoguard-content-safety) | Validates request and/or response content using NVIDIA NeMo Guard (llama-3.1-nemoguard-8b-content-safety) | +## Add or update guardrails + +A guardrail is a gateway policy, so you add or update one by editing the gateway's `build.yaml` and rebuilding the image with the `ap` CLI. See [Add or Update Policies in a Gateway](../../../api-gateway/next/policies/add-or-update-policies.md). + ## Custom guardrails -You can extend the AI Gateway with custom guardrail policies by building a custom gateway image using the `ap` CLI. See [Customizing the Gateway by Adding and Removing Policies](../../../tools/cli/customizing-gateway-policies.md). +To write your own guardrail policy in Go and build it into the gateway image, see [Writing a Custom Policy](../../../api-gateway/next/policies/custom-policies/writing-a-custom-policy.md). ## Related topics diff --git a/en/docs/api-gateway/1.0.0/policies/add-or-update-policies.md b/en/docs/api-gateway/1.0.0/policies/add-or-update-policies.md new file mode 100644 index 0000000000..f217ae34de --- /dev/null +++ b/en/docs/api-gateway/1.0.0/policies/add-or-update-policies.md @@ -0,0 +1,193 @@ +--- +title: "Add or Update Policies in a Gateway" +description: "Add a Policy Hub or local policy to an API Platform Gateway, or update a policy to a different version, by editing build.yaml and rebuilding the image." +canonical_url: https://wso2.com/api-platform/docs/api-gateway/policies/add-or-update-policies/ +md_url: https://wso2.com/api-platform/docs/api-gateway/policies/add-or-update-policies.md +tags: + - api-gateway + - policies + - cli + - policy-hub +author: WSO2 API Platform Documentation Team +last_updated: 2026-09-15 +content_type: "how-to" +--- + +# Add or Update Policies in a Gateway + +A gateway compiles its policies into the gateway image when the image is built. To add a policy, update a policy to a different version, or remove one, edit the `policies` list in the gateway's `build.yaml` file and rebuild the image with the API Platform CLI (`ap`). This works the same way for managed policies from the [Policy Hub](../../../policy-hub/overview.md) and for your own local policies. + +!!! note + Policies are part of the gateway image. A policy change takes effect after you rebuild the image and restart the gateway. + +For the concepts behind policies and the list of available policies, see the [API Platform Policies overview](overview.md). To write your own policy, see [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md). + +## Prerequisites + +- The API Platform CLI (`ap`), version 0.9.1 or later. Download the binary for your platform from the [`ap` CLI v0.9.1 release page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.9.1), then add it to your `PATH`. For step-by-step installation instructions, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). Confirm the version: + + ```bash + ap version + ``` + + The output is similar to `ap version v0.9.1 (built at 2026-08-01T00:00:00Z)`. + +- Docker, running on your machine. The CLI uses Docker to build the gateway image. +- A gateway project directory that contains a `build.yaml` file. + +## How policies are declared in build.yaml + +The `build.yaml` file lists every policy compiled into the gateway image. Each entry under `policies` has a `name` and exactly one source field that tells the build where to get the policy: + +| Field | Policy type | Value | +|---|---|---| +| `gomodule` | Managed policy from the Policy Hub | Go module reference in the form `github.com/wso2/gateway-controllers/policies/@` | +| `filePath` | Local policy | Path to the policy directory, relative to `build.yaml` | + +A `build.yaml` with one Policy Hub policy and one local policy looks like this: + +```yaml +version: v1 +gateway: + version: 1.0.0 +policies: + - name: set-headers + gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1 + - name: my-policy + filePath: ./policies/my-policy +``` + +The `name` of a local policy must match the `name` in that policy's `policy-definition.yaml`. For the full `build.yaml` reference, including base-image overrides, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +### Policy versions + +For a managed policy, the version qualifier in its `gomodule` reference controls which release the build includes. You can pin a policy to a major, minor, or exact version: + +| Qualifier | Selects | Example | +|---|---|---| +| `@v1` | The most recent release in the `v1` major line | `github.com/wso2/gateway-controllers/policies/set-headers@v1` | +| `@v1.1` | The most recent patch release in the `v1.1` minor line | `github.com/wso2/gateway-controllers/policies/set-headers@v1.1` | +| `@v1.1.0` | Exactly version `v1.1.0` | `github.com/wso2/gateway-controllers/policies/set-headers@v1.1.0` | + +!!! note + A partial qualifier always resolves to the highest matching release. `@v1` selects the highest available `v1` release, `@v1.1` selects the highest available patch release in the `v1.1` line, and `@v1.1.0` pins exactly that version. + +For a local policy, the version comes from the `version` field in its `policy-definition.yaml`. + +Each build resolves every reference to a concrete version and records it in `build-manifest.yaml`. + +## Add a policy + +### Add a managed policy from the Policy Hub + +1. Find the module reference of the policy you want to add. Each policy in the [Available Policies](overview.md#available-policies) list links to its documentation, which gives the module path. +2. Open the gateway's `build.yaml` file. +3. Add an entry under `policies` with the policy `name` and its `gomodule` reference. For example, to add the CORS policy: + + ```yaml + policies: + - name: cors + gomodule: github.com/wso2/gateway-controllers/policies/cors@v1 + ``` + + The `@v1` qualifier selects the most recent `v1` release. To pin a specific version, see [Policy versions](#policy-versions). + +4. [Rebuild the gateway image](#rebuild-the-gateway-image). + +### Add a local policy + +1. Place the policy directory where the build can reach it by a path relative to `build.yaml`. The directory holds the policy implementation and a `policy-definition.yaml`. To write one, see [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md). +2. Add an entry under `policies` with the policy `name` and a `filePath` that points to the directory: + + ```yaml + policies: + - name: my-policy + filePath: ./policies/my-policy + ``` + + The `name` must match the `name` in the policy's `policy-definition.yaml`. + +3. [Rebuild the gateway image](#rebuild-the-gateway-image). + +## Update a policy + +### Update a managed policy + +To update a managed policy, change its version qualifier and rebuild. For example, to pin the `set-headers` policy to an exact version: + +```yaml +policies: + - name: set-headers + gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1.1.0 +``` + +For the major, minor, and exact qualifier forms, see [Policy versions](#policy-versions). When you reference a major or minor line, each rebuild picks up the most recent matching release; to hold a policy at a fixed version, reference the exact version. After the build, check the `build-manifest.yaml` file next to `build.yaml` to confirm the version included. + +### Update a local policy + +1. Update the policy's implementation, and set the new version in the `version` field of its `policy-definition.yaml`. +2. [Rebuild the gateway image](#rebuild-the-gateway-image). + +## Remove a policy + +To remove a policy, delete its entry from the `policies` list in `build.yaml`, then [rebuild the gateway image](#rebuild-the-gateway-image). + +## Rebuild the gateway image + +Run the following command from the directory that contains `build.yaml`: + +```bash +ap gateway image build +``` + +The command: + +- Builds a `gateway-runtime` image and a `gateway-controller` image that include the policies listed in `build.yaml`, and prints both image names. +- Names each image `/-gateway-runtime:`, where `` defaults to the name of the directory that contains `build.yaml`. +- Writes a `build-manifest.yaml` file next to `build.yaml` that records the resolved policy versions. + +To set a different image name, pass the `--name` flag: + +```bash +ap gateway image build --name my-gateway +``` + +For the full list of build options and base-image configuration, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +## Apply the change + +1. If this is the first time you build the gateway image, update the `image` field of the `gateway-controller` and `gateway-runtime` services in your `docker-compose.yaml` to the names from the build output. For example, for a gateway built with `--name my-gateway`, change the base images: + + ```yaml + services: + gateway-controller: + image: ghcr.io/wso2/api-platform/gateway-controller:1.0.0 + gateway-runtime: + image: ghcr.io/wso2/api-platform/gateway-runtime:1.0.0 + ``` + + to the built images: + + ```yaml + services: + gateway-controller: + image: ghcr.io/wso2/api-platform/my-gateway-gateway-controller:1.0.0 + gateway-runtime: + image: ghcr.io/wso2/api-platform/my-gateway-gateway-runtime:1.0.0 + ``` + + On later updates that keep the same name and version, the image names do not change, so you can leave `docker-compose.yaml` as it is. For the full steps, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). +2. Recreate the gateway containers so they use the rebuilt images: + + ```bash + docker compose up -d --force-recreate + ``` + +To attach an added or updated policy to an API, add it to the API definition. For an example, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +## What's next + +- [API Platform Policies overview](overview.md): Concepts and the list of available policies. +- [Policy execution order](policy-execution-order.md): How chained policies run on a request and response. +- [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md): Build your own policy in Go. +- [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md): The full gateway image build workflow. diff --git a/en/docs/api-gateway/1.0.0/policies/custom-policies/building-gateway-with-custom-policies.md b/en/docs/api-gateway/1.0.0/policies/custom-policies/building-gateway-with-custom-policies.md index 48ef377c69..9dd44ec993 100644 --- a/en/docs/api-gateway/1.0.0/policies/custom-policies/building-gateway-with-custom-policies.md +++ b/en/docs/api-gateway/1.0.0/policies/custom-policies/building-gateway-with-custom-policies.md @@ -17,7 +17,7 @@ content_type: "how-to" ## 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 releases page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.7.0) and follow the steps below to install it. +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](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.9.1) and follow the steps below to install it. === "macOS / Linux" @@ -26,14 +26,16 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies After downloading the zip file for your platform, extract it: ```bash - unzip ap-darwin-amd64-v0.7.0.zip # replace with your downloaded filename + unzip ap---v0.9.1.zip # replace with the file you downloaded ``` + Extracting the archive creates a folder of the same name that contains the `ap` binary. + **Step 2: Move the binary to a bin directory** ```bash mkdir -p ~/bin - mv ap ~/bin/ + mv ap---v0.9.1/ap ~/bin/ ``` **Step 3: Add to PATH** @@ -53,7 +55,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies **Step 5: Verify the installation** ```bash - ap --version + ap version ``` === "Windows" @@ -63,14 +65,16 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies After downloading the zip file, right-click it and select **Extract All**, or run in PowerShell: ```powershell - Expand-Archive -Path ap-windows-amd64.zip -DestinationPath ap-windows-amd64 + Expand-Archive -Path ap-windows--v0.9.1.zip -DestinationPath . ``` + Extracting the archive creates a folder of the same name that contains `ap.exe`. + **Step 2: Move the binary to a bin directory** ```powershell New-Item -ItemType Directory -Force -Path "$HOME\bin" - Move-Item ap-windows-amd64\ap.exe "$HOME\bin\ap.exe" + Move-Item ap-windows--v0.9.1\ap.exe "$HOME\bin\ap.exe" ``` **Step 3: Add to PATH** @@ -88,7 +92,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies **Step 5: Verify the installation** ```powershell - ap --version + ap version ``` ## Configure the Build File diff --git a/en/docs/api-gateway/1.1.0/policies/add-or-update-policies.md b/en/docs/api-gateway/1.1.0/policies/add-or-update-policies.md new file mode 100644 index 0000000000..25b7416c51 --- /dev/null +++ b/en/docs/api-gateway/1.1.0/policies/add-or-update-policies.md @@ -0,0 +1,193 @@ +--- +title: "Add or Update Policies in a Gateway" +description: "Add a Policy Hub or local policy to an API Platform Gateway, or update a policy to a different version, by editing build.yaml and rebuilding the image." +canonical_url: https://wso2.com/api-platform/docs/api-gateway/policies/add-or-update-policies/ +md_url: https://wso2.com/api-platform/docs/api-gateway/policies/add-or-update-policies.md +tags: + - api-gateway + - policies + - cli + - policy-hub +author: WSO2 API Platform Documentation Team +last_updated: 2026-09-15 +content_type: "how-to" +--- + +# Add or Update Policies in a Gateway + +A gateway compiles its policies into the gateway image when the image is built. To add a policy, update a policy to a different version, or remove one, edit the `policies` list in the gateway's `build.yaml` file and rebuild the image with the API Platform CLI (`ap`). This works the same way for managed policies from the [Policy Hub](../../../policy-hub/overview.md) and for your own local policies. + +!!! note + Policies are part of the gateway image. A policy change takes effect after you rebuild the image and restart the gateway. + +For the concepts behind policies and the list of available policies, see the [API Platform Policies overview](overview.md). To write your own policy, see [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md). + +## Prerequisites + +- The API Platform CLI (`ap`), version 0.9.1 or later. Download the binary for your platform from the [`ap` CLI v0.9.1 release page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.9.1), then add it to your `PATH`. For step-by-step installation instructions, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). Confirm the version: + + ```bash + ap version + ``` + + The output is similar to `ap version v0.9.1 (built at 2026-08-01T00:00:00Z)`. + +- Docker, running on your machine. The CLI uses Docker to build the gateway image. +- A gateway project directory that contains a `build.yaml` file. + +## How policies are declared in build.yaml + +The `build.yaml` file lists every policy compiled into the gateway image. Each entry under `policies` has a `name` and exactly one source field that tells the build where to get the policy: + +| Field | Policy type | Value | +|---|---|---| +| `gomodule` | Managed policy from the Policy Hub | Go module reference in the form `github.com/wso2/gateway-controllers/policies/@` | +| `filePath` | Local policy | Path to the policy directory, relative to `build.yaml` | + +A `build.yaml` with one Policy Hub policy and one local policy looks like this: + +```yaml +version: v1 +gateway: + version: 1.1.0 +policies: + - name: set-headers + gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1 + - name: my-policy + filePath: ./policies/my-policy +``` + +The `name` of a local policy must match the `name` in that policy's `policy-definition.yaml`. For the full `build.yaml` reference, including base-image overrides, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +### Policy versions + +For a managed policy, the version qualifier in its `gomodule` reference controls which release the build includes. You can pin a policy to a major, minor, or exact version: + +| Qualifier | Selects | Example | +|---|---|---| +| `@v1` | The most recent release in the `v1` major line | `github.com/wso2/gateway-controllers/policies/set-headers@v1` | +| `@v1.1` | The most recent patch release in the `v1.1` minor line | `github.com/wso2/gateway-controllers/policies/set-headers@v1.1` | +| `@v1.1.0` | Exactly version `v1.1.0` | `github.com/wso2/gateway-controllers/policies/set-headers@v1.1.0` | + +!!! note + A partial qualifier always resolves to the highest matching release. `@v1` selects the highest available `v1` release, `@v1.1` selects the highest available patch release in the `v1.1` line, and `@v1.1.0` pins exactly that version. + +For a local policy, the version comes from the `version` field in its `policy-definition.yaml`. + +Each build resolves every reference to a concrete version and records it in `build-manifest.yaml`. + +## Add a policy + +### Add a managed policy from the Policy Hub + +1. Find the module reference of the policy you want to add. Each policy in the [Available Policies](overview.md#available-policies) list links to its documentation, which gives the module path. +2. Open the gateway's `build.yaml` file. +3. Add an entry under `policies` with the policy `name` and its `gomodule` reference. For example, to add the CORS policy: + + ```yaml + policies: + - name: cors + gomodule: github.com/wso2/gateway-controllers/policies/cors@v1 + ``` + + The `@v1` qualifier selects the most recent `v1` release. To pin a specific version, see [Policy versions](#policy-versions). + +4. [Rebuild the gateway image](#rebuild-the-gateway-image). + +### Add a local policy + +1. Place the policy directory where the build can reach it by a path relative to `build.yaml`. The directory holds the policy implementation and a `policy-definition.yaml`. To write one, see [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md). +2. Add an entry under `policies` with the policy `name` and a `filePath` that points to the directory: + + ```yaml + policies: + - name: my-policy + filePath: ./policies/my-policy + ``` + + The `name` must match the `name` in the policy's `policy-definition.yaml`. + +3. [Rebuild the gateway image](#rebuild-the-gateway-image). + +## Update a policy + +### Update a managed policy + +To update a managed policy, change its version qualifier and rebuild. For example, to pin the `set-headers` policy to an exact version: + +```yaml +policies: + - name: set-headers + gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1.1.0 +``` + +For the major, minor, and exact qualifier forms, see [Policy versions](#policy-versions). When you reference a major or minor line, each rebuild picks up the most recent matching release; to hold a policy at a fixed version, reference the exact version. After the build, check the `build-manifest.yaml` file next to `build.yaml` to confirm the version included. + +### Update a local policy + +1. Update the policy's implementation, and set the new version in the `version` field of its `policy-definition.yaml`. +2. [Rebuild the gateway image](#rebuild-the-gateway-image). + +## Remove a policy + +To remove a policy, delete its entry from the `policies` list in `build.yaml`, then [rebuild the gateway image](#rebuild-the-gateway-image). + +## Rebuild the gateway image + +Run the following command from the directory that contains `build.yaml`: + +```bash +ap gateway image build +``` + +The command: + +- Builds a `gateway-runtime` image and a `gateway-controller` image that include the policies listed in `build.yaml`, and prints both image names. +- Names each image `/-gateway-runtime:`, where `` defaults to the name of the directory that contains `build.yaml`. +- Writes a `build-manifest.yaml` file next to `build.yaml` that records the resolved policy versions. + +To set a different image name, pass the `--name` flag: + +```bash +ap gateway image build --name my-gateway +``` + +For the full list of build options and base-image configuration, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +## Apply the change + +1. If this is the first time you build the gateway image, update the `image` field of the `gateway-controller` and `gateway-runtime` services in your `docker-compose.yaml` to the names from the build output. For example, for a gateway built with `--name my-gateway`, change the base images: + + ```yaml + services: + gateway-controller: + image: ghcr.io/wso2/api-platform/gateway-controller:1.1.0 + gateway-runtime: + image: ghcr.io/wso2/api-platform/gateway-runtime:1.1.0 + ``` + + to the built images: + + ```yaml + services: + gateway-controller: + image: ghcr.io/wso2/api-platform/my-gateway-gateway-controller:1.1.0 + gateway-runtime: + image: ghcr.io/wso2/api-platform/my-gateway-gateway-runtime:1.1.0 + ``` + + On later updates that keep the same name and version, the image names do not change, so you can leave `docker-compose.yaml` as it is. For the full steps, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). +2. Recreate the gateway containers so they use the rebuilt images: + + ```bash + docker compose up -d --force-recreate + ``` + +To attach an added or updated policy to an API, add it to the API definition. For an example, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +## What's next + +- [API Platform Policies overview](overview.md): Concepts and the list of available policies. +- [Policy execution order](policy-execution-order.md): How chained policies run on a request and response. +- [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md): Build your own policy in Go. +- [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md): The full gateway image build workflow. diff --git a/en/docs/api-gateway/1.1.0/policies/custom-policies/building-gateway-with-custom-policies.md b/en/docs/api-gateway/1.1.0/policies/custom-policies/building-gateway-with-custom-policies.md index 48ef377c69..9dd44ec993 100644 --- a/en/docs/api-gateway/1.1.0/policies/custom-policies/building-gateway-with-custom-policies.md +++ b/en/docs/api-gateway/1.1.0/policies/custom-policies/building-gateway-with-custom-policies.md @@ -17,7 +17,7 @@ content_type: "how-to" ## 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 releases page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.7.0) and follow the steps below to install it. +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](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.9.1) and follow the steps below to install it. === "macOS / Linux" @@ -26,14 +26,16 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies After downloading the zip file for your platform, extract it: ```bash - unzip ap-darwin-amd64-v0.7.0.zip # replace with your downloaded filename + unzip ap---v0.9.1.zip # replace with the file you downloaded ``` + Extracting the archive creates a folder of the same name that contains the `ap` binary. + **Step 2: Move the binary to a bin directory** ```bash mkdir -p ~/bin - mv ap ~/bin/ + mv ap---v0.9.1/ap ~/bin/ ``` **Step 3: Add to PATH** @@ -53,7 +55,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies **Step 5: Verify the installation** ```bash - ap --version + ap version ``` === "Windows" @@ -63,14 +65,16 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies After downloading the zip file, right-click it and select **Extract All**, or run in PowerShell: ```powershell - Expand-Archive -Path ap-windows-amd64.zip -DestinationPath ap-windows-amd64 + Expand-Archive -Path ap-windows--v0.9.1.zip -DestinationPath . ``` + Extracting the archive creates a folder of the same name that contains `ap.exe`. + **Step 2: Move the binary to a bin directory** ```powershell New-Item -ItemType Directory -Force -Path "$HOME\bin" - Move-Item ap-windows-amd64\ap.exe "$HOME\bin\ap.exe" + Move-Item ap-windows--v0.9.1\ap.exe "$HOME\bin\ap.exe" ``` **Step 3: Add to PATH** @@ -88,7 +92,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies **Step 5: Verify the installation** ```powershell - ap --version + ap version ``` ## Configure the Build File diff --git a/en/docs/api-gateway/1.2.0/policies/add-or-update-policies.md b/en/docs/api-gateway/1.2.0/policies/add-or-update-policies.md new file mode 100644 index 0000000000..837dfbb300 --- /dev/null +++ b/en/docs/api-gateway/1.2.0/policies/add-or-update-policies.md @@ -0,0 +1,193 @@ +--- +title: "Add or Update Policies in a Gateway" +description: "Add a Policy Hub or local policy to an API Platform Gateway, or update a policy to a different version, by editing build.yaml and rebuilding the image." +canonical_url: https://wso2.com/api-platform/docs/api-gateway/policies/add-or-update-policies/ +md_url: https://wso2.com/api-platform/docs/api-gateway/policies/add-or-update-policies.md +tags: + - api-gateway + - policies + - cli + - policy-hub +author: WSO2 API Platform Documentation Team +last_updated: 2026-09-15 +content_type: "how-to" +--- + +# Add or Update Policies in a Gateway + +A gateway compiles its policies into the gateway image when the image is built. To add a policy, update a policy to a different version, or remove one, edit the `policies` list in the gateway's `build.yaml` file and rebuild the image with the API Platform CLI (`ap`). This works the same way for managed policies from the [Policy Hub](../../../policy-hub/overview.md) and for your own local policies. + +!!! note + Policies are part of the gateway image. A policy change takes effect after you rebuild the image and restart the gateway. + +For the concepts behind policies and the list of available policies, see the [API Platform Policies overview](overview.md). To write your own policy, see [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md). + +## Prerequisites + +- The API Platform CLI (`ap`), version 0.9.1 or later. Download the binary for your platform from the [`ap` CLI v0.9.1 release page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.9.1), then add it to your `PATH`. For step-by-step installation instructions, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). Confirm the version: + + ```bash + ap version + ``` + + The output is similar to `ap version v0.9.1 (built at 2026-08-01T00:00:00Z)`. + +- Docker, running on your machine. The CLI uses Docker to build the gateway image. +- A gateway project directory that contains a `build.yaml` file. + +## How policies are declared in build.yaml + +The `build.yaml` file lists every policy compiled into the gateway image. Each entry under `policies` has a `name` and exactly one source field that tells the build where to get the policy: + +| Field | Policy type | Value | +|---|---|---| +| `gomodule` | Managed policy from the Policy Hub | Go module reference in the form `github.com/wso2/gateway-controllers/policies/@` | +| `filePath` | Local policy | Path to the policy directory, relative to `build.yaml` | + +A `build.yaml` with one Policy Hub policy and one local policy looks like this: + +```yaml +version: v1 +gateway: + version: 1.2.0 +policies: + - name: set-headers + gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1 + - name: my-policy + filePath: ./policies/my-policy +``` + +The `name` of a local policy must match the `name` in that policy's `policy-definition.yaml`. For the full `build.yaml` reference, including base-image overrides, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +### Policy versions + +For a managed policy, the version qualifier in its `gomodule` reference controls which release the build includes. You can pin a policy to a major, minor, or exact version: + +| Qualifier | Selects | Example | +|---|---|---| +| `@v1` | The most recent release in the `v1` major line | `github.com/wso2/gateway-controllers/policies/set-headers@v1` | +| `@v1.1` | The most recent patch release in the `v1.1` minor line | `github.com/wso2/gateway-controllers/policies/set-headers@v1.1` | +| `@v1.1.0` | Exactly version `v1.1.0` | `github.com/wso2/gateway-controllers/policies/set-headers@v1.1.0` | + +!!! note + A partial qualifier always resolves to the highest matching release. `@v1` selects the highest available `v1` release, `@v1.1` selects the highest available patch release in the `v1.1` line, and `@v1.1.0` pins exactly that version. + +For a local policy, the version comes from the `version` field in its `policy-definition.yaml`. + +Each build resolves every reference to a concrete version and records it in `build-manifest.yaml`. + +## Add a policy + +### Add a managed policy from the Policy Hub + +1. Find the module reference of the policy you want to add. Each policy in the [Available Policies](overview.md#available-policies) list links to its documentation, which gives the module path. +2. Open the gateway's `build.yaml` file. +3. Add an entry under `policies` with the policy `name` and its `gomodule` reference. For example, to add the CORS policy: + + ```yaml + policies: + - name: cors + gomodule: github.com/wso2/gateway-controllers/policies/cors@v1 + ``` + + The `@v1` qualifier selects the most recent `v1` release. To pin a specific version, see [Policy versions](#policy-versions). + +4. [Rebuild the gateway image](#rebuild-the-gateway-image). + +### Add a local policy + +1. Place the policy directory where the build can reach it by a path relative to `build.yaml`. The directory holds the policy implementation and a `policy-definition.yaml`. To write one, see [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md). +2. Add an entry under `policies` with the policy `name` and a `filePath` that points to the directory: + + ```yaml + policies: + - name: my-policy + filePath: ./policies/my-policy + ``` + + The `name` must match the `name` in the policy's `policy-definition.yaml`. + +3. [Rebuild the gateway image](#rebuild-the-gateway-image). + +## Update a policy + +### Update a managed policy + +To update a managed policy, change its version qualifier and rebuild. For example, to pin the `set-headers` policy to an exact version: + +```yaml +policies: + - name: set-headers + gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1.1.0 +``` + +For the major, minor, and exact qualifier forms, see [Policy versions](#policy-versions). When you reference a major or minor line, each rebuild picks up the most recent matching release; to hold a policy at a fixed version, reference the exact version. After the build, check the `build-manifest.yaml` file next to `build.yaml` to confirm the version included. + +### Update a local policy + +1. Update the policy's implementation, and set the new version in the `version` field of its `policy-definition.yaml`. +2. [Rebuild the gateway image](#rebuild-the-gateway-image). + +## Remove a policy + +To remove a policy, delete its entry from the `policies` list in `build.yaml`, then [rebuild the gateway image](#rebuild-the-gateway-image). + +## Rebuild the gateway image + +Run the following command from the directory that contains `build.yaml`: + +```bash +ap gateway image build +``` + +The command: + +- Builds a `gateway-runtime` image and a `gateway-controller` image that include the policies listed in `build.yaml`, and prints both image names. +- Names each image `/-gateway-runtime:`, where `` defaults to the name of the directory that contains `build.yaml`. +- Writes a `build-manifest.yaml` file next to `build.yaml` that records the resolved policy versions. + +To set a different image name, pass the `--name` flag: + +```bash +ap gateway image build --name my-gateway +``` + +For the full list of build options and base-image configuration, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +## Apply the change + +1. If this is the first time you build the gateway image, update the `image` field of the `gateway-controller` and `gateway-runtime` services in your `docker-compose.yaml` to the names from the build output. For example, for a gateway built with `--name my-gateway`, change the base images: + + ```yaml + services: + gateway-controller: + image: ghcr.io/wso2/api-platform/gateway-controller:1.2.0 + gateway-runtime: + image: ghcr.io/wso2/api-platform/gateway-runtime:1.2.0 + ``` + + to the built images: + + ```yaml + services: + gateway-controller: + image: ghcr.io/wso2/api-platform/my-gateway-gateway-controller:1.2.0 + gateway-runtime: + image: ghcr.io/wso2/api-platform/my-gateway-gateway-runtime:1.2.0 + ``` + + On later updates that keep the same name and version, the image names do not change, so you can leave `docker-compose.yaml` as it is. For the full steps, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). +2. Recreate the gateway containers so they use the rebuilt images: + + ```bash + docker compose up -d --force-recreate + ``` + +To attach an added or updated policy to an API, add it to the API definition. For an example, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +## What's next + +- [API Platform Policies overview](overview.md): Concepts and the list of available policies. +- [Policy execution order](policy-execution-order.md): How chained policies run on a request and response. +- [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md): Build your own policy in Go. +- [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md): The full gateway image build workflow. diff --git a/en/docs/api-gateway/1.2.0/policies/custom-policies/building-gateway-with-custom-policies.md b/en/docs/api-gateway/1.2.0/policies/custom-policies/building-gateway-with-custom-policies.md index fc2aa0eb67..858023c91f 100644 --- a/en/docs/api-gateway/1.2.0/policies/custom-policies/building-gateway-with-custom-policies.md +++ b/en/docs/api-gateway/1.2.0/policies/custom-policies/building-gateway-with-custom-policies.md @@ -17,7 +17,7 @@ content_type: "how-to" ## 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 releases page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.7.0) and follow the steps below to install it. +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](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.9.1) and follow the steps below to install it. === "macOS / Linux" @@ -26,14 +26,16 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies After downloading the zip file for your platform, extract it: ```bash - unzip ap-darwin-amd64-v0.7.0.zip # replace with your downloaded filename + unzip ap---v0.9.1.zip # replace with the file you downloaded ``` + Extracting the archive creates a folder of the same name that contains the `ap` binary. + **Step 2: Move the binary to a bin directory** ```bash mkdir -p ~/bin - mv ap ~/bin/ + mv ap---v0.9.1/ap ~/bin/ ``` **Step 3: Add to PATH** @@ -53,7 +55,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies **Step 5: Verify the installation** ```bash - ap --version + ap version ``` === "Windows" @@ -63,14 +65,16 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies After downloading the zip file, right-click it and select **Extract All**, or run in PowerShell: ```powershell - Expand-Archive -Path ap-windows-amd64.zip -DestinationPath ap-windows-amd64 + Expand-Archive -Path ap-windows--v0.9.1.zip -DestinationPath . ``` + Extracting the archive creates a folder of the same name that contains `ap.exe`. + **Step 2: Move the binary to a bin directory** ```powershell New-Item -ItemType Directory -Force -Path "$HOME\bin" - Move-Item ap-windows-amd64\ap.exe "$HOME\bin\ap.exe" + Move-Item ap-windows--v0.9.1\ap.exe "$HOME\bin\ap.exe" ``` **Step 3: Add to PATH** @@ -88,7 +92,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies **Step 5: Verify the installation** ```powershell - ap --version + ap version ``` ## Configure the Build File diff --git a/en/docs/api-gateway/next/policies/add-or-update-policies.md b/en/docs/api-gateway/next/policies/add-or-update-policies.md new file mode 100644 index 0000000000..837dfbb300 --- /dev/null +++ b/en/docs/api-gateway/next/policies/add-or-update-policies.md @@ -0,0 +1,193 @@ +--- +title: "Add or Update Policies in a Gateway" +description: "Add a Policy Hub or local policy to an API Platform Gateway, or update a policy to a different version, by editing build.yaml and rebuilding the image." +canonical_url: https://wso2.com/api-platform/docs/api-gateway/policies/add-or-update-policies/ +md_url: https://wso2.com/api-platform/docs/api-gateway/policies/add-or-update-policies.md +tags: + - api-gateway + - policies + - cli + - policy-hub +author: WSO2 API Platform Documentation Team +last_updated: 2026-09-15 +content_type: "how-to" +--- + +# Add or Update Policies in a Gateway + +A gateway compiles its policies into the gateway image when the image is built. To add a policy, update a policy to a different version, or remove one, edit the `policies` list in the gateway's `build.yaml` file and rebuild the image with the API Platform CLI (`ap`). This works the same way for managed policies from the [Policy Hub](../../../policy-hub/overview.md) and for your own local policies. + +!!! note + Policies are part of the gateway image. A policy change takes effect after you rebuild the image and restart the gateway. + +For the concepts behind policies and the list of available policies, see the [API Platform Policies overview](overview.md). To write your own policy, see [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md). + +## Prerequisites + +- The API Platform CLI (`ap`), version 0.9.1 or later. Download the binary for your platform from the [`ap` CLI v0.9.1 release page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.9.1), then add it to your `PATH`. For step-by-step installation instructions, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). Confirm the version: + + ```bash + ap version + ``` + + The output is similar to `ap version v0.9.1 (built at 2026-08-01T00:00:00Z)`. + +- Docker, running on your machine. The CLI uses Docker to build the gateway image. +- A gateway project directory that contains a `build.yaml` file. + +## How policies are declared in build.yaml + +The `build.yaml` file lists every policy compiled into the gateway image. Each entry under `policies` has a `name` and exactly one source field that tells the build where to get the policy: + +| Field | Policy type | Value | +|---|---|---| +| `gomodule` | Managed policy from the Policy Hub | Go module reference in the form `github.com/wso2/gateway-controllers/policies/@` | +| `filePath` | Local policy | Path to the policy directory, relative to `build.yaml` | + +A `build.yaml` with one Policy Hub policy and one local policy looks like this: + +```yaml +version: v1 +gateway: + version: 1.2.0 +policies: + - name: set-headers + gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1 + - name: my-policy + filePath: ./policies/my-policy +``` + +The `name` of a local policy must match the `name` in that policy's `policy-definition.yaml`. For the full `build.yaml` reference, including base-image overrides, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +### Policy versions + +For a managed policy, the version qualifier in its `gomodule` reference controls which release the build includes. You can pin a policy to a major, minor, or exact version: + +| Qualifier | Selects | Example | +|---|---|---| +| `@v1` | The most recent release in the `v1` major line | `github.com/wso2/gateway-controllers/policies/set-headers@v1` | +| `@v1.1` | The most recent patch release in the `v1.1` minor line | `github.com/wso2/gateway-controllers/policies/set-headers@v1.1` | +| `@v1.1.0` | Exactly version `v1.1.0` | `github.com/wso2/gateway-controllers/policies/set-headers@v1.1.0` | + +!!! note + A partial qualifier always resolves to the highest matching release. `@v1` selects the highest available `v1` release, `@v1.1` selects the highest available patch release in the `v1.1` line, and `@v1.1.0` pins exactly that version. + +For a local policy, the version comes from the `version` field in its `policy-definition.yaml`. + +Each build resolves every reference to a concrete version and records it in `build-manifest.yaml`. + +## Add a policy + +### Add a managed policy from the Policy Hub + +1. Find the module reference of the policy you want to add. Each policy in the [Available Policies](overview.md#available-policies) list links to its documentation, which gives the module path. +2. Open the gateway's `build.yaml` file. +3. Add an entry under `policies` with the policy `name` and its `gomodule` reference. For example, to add the CORS policy: + + ```yaml + policies: + - name: cors + gomodule: github.com/wso2/gateway-controllers/policies/cors@v1 + ``` + + The `@v1` qualifier selects the most recent `v1` release. To pin a specific version, see [Policy versions](#policy-versions). + +4. [Rebuild the gateway image](#rebuild-the-gateway-image). + +### Add a local policy + +1. Place the policy directory where the build can reach it by a path relative to `build.yaml`. The directory holds the policy implementation and a `policy-definition.yaml`. To write one, see [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md). +2. Add an entry under `policies` with the policy `name` and a `filePath` that points to the directory: + + ```yaml + policies: + - name: my-policy + filePath: ./policies/my-policy + ``` + + The `name` must match the `name` in the policy's `policy-definition.yaml`. + +3. [Rebuild the gateway image](#rebuild-the-gateway-image). + +## Update a policy + +### Update a managed policy + +To update a managed policy, change its version qualifier and rebuild. For example, to pin the `set-headers` policy to an exact version: + +```yaml +policies: + - name: set-headers + gomodule: github.com/wso2/gateway-controllers/policies/set-headers@v1.1.0 +``` + +For the major, minor, and exact qualifier forms, see [Policy versions](#policy-versions). When you reference a major or minor line, each rebuild picks up the most recent matching release; to hold a policy at a fixed version, reference the exact version. After the build, check the `build-manifest.yaml` file next to `build.yaml` to confirm the version included. + +### Update a local policy + +1. Update the policy's implementation, and set the new version in the `version` field of its `policy-definition.yaml`. +2. [Rebuild the gateway image](#rebuild-the-gateway-image). + +## Remove a policy + +To remove a policy, delete its entry from the `policies` list in `build.yaml`, then [rebuild the gateway image](#rebuild-the-gateway-image). + +## Rebuild the gateway image + +Run the following command from the directory that contains `build.yaml`: + +```bash +ap gateway image build +``` + +The command: + +- Builds a `gateway-runtime` image and a `gateway-controller` image that include the policies listed in `build.yaml`, and prints both image names. +- Names each image `/-gateway-runtime:`, where `` defaults to the name of the directory that contains `build.yaml`. +- Writes a `build-manifest.yaml` file next to `build.yaml` that records the resolved policy versions. + +To set a different image name, pass the `--name` flag: + +```bash +ap gateway image build --name my-gateway +``` + +For the full list of build options and base-image configuration, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +## Apply the change + +1. If this is the first time you build the gateway image, update the `image` field of the `gateway-controller` and `gateway-runtime` services in your `docker-compose.yaml` to the names from the build output. For example, for a gateway built with `--name my-gateway`, change the base images: + + ```yaml + services: + gateway-controller: + image: ghcr.io/wso2/api-platform/gateway-controller:1.2.0 + gateway-runtime: + image: ghcr.io/wso2/api-platform/gateway-runtime:1.2.0 + ``` + + to the built images: + + ```yaml + services: + gateway-controller: + image: ghcr.io/wso2/api-platform/my-gateway-gateway-controller:1.2.0 + gateway-runtime: + image: ghcr.io/wso2/api-platform/my-gateway-gateway-runtime:1.2.0 + ``` + + On later updates that keep the same name and version, the image names do not change, so you can leave `docker-compose.yaml` as it is. For the full steps, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). +2. Recreate the gateway containers so they use the rebuilt images: + + ```bash + docker compose up -d --force-recreate + ``` + +To attach an added or updated policy to an API, add it to the API definition. For an example, see [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md). + +## What's next + +- [API Platform Policies overview](overview.md): Concepts and the list of available policies. +- [Policy execution order](policy-execution-order.md): How chained policies run on a request and response. +- [Writing a Custom Policy](custom-policies/writing-a-custom-policy.md): Build your own policy in Go. +- [Building the Gateway with Custom Policies](custom-policies/building-gateway-with-custom-policies.md): The full gateway image build workflow. diff --git a/en/docs/api-gateway/next/policies/custom-policies/building-gateway-with-custom-policies.md b/en/docs/api-gateway/next/policies/custom-policies/building-gateway-with-custom-policies.md index fc2aa0eb67..858023c91f 100644 --- a/en/docs/api-gateway/next/policies/custom-policies/building-gateway-with-custom-policies.md +++ b/en/docs/api-gateway/next/policies/custom-policies/building-gateway-with-custom-policies.md @@ -17,7 +17,7 @@ content_type: "how-to" ## 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 releases page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.7.0) and follow the steps below to install it. +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](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.9.1) and follow the steps below to install it. === "macOS / Linux" @@ -26,14 +26,16 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies After downloading the zip file for your platform, extract it: ```bash - unzip ap-darwin-amd64-v0.7.0.zip # replace with your downloaded filename + unzip ap---v0.9.1.zip # replace with the file you downloaded ``` + Extracting the archive creates a folder of the same name that contains the `ap` binary. + **Step 2: Move the binary to a bin directory** ```bash mkdir -p ~/bin - mv ap ~/bin/ + mv ap---v0.9.1/ap ~/bin/ ``` **Step 3: Add to PATH** @@ -53,7 +55,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies **Step 5: Verify the installation** ```bash - ap --version + ap version ``` === "Windows" @@ -63,14 +65,16 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies After downloading the zip file, right-click it and select **Extract All**, or run in PowerShell: ```powershell - Expand-Archive -Path ap-windows-amd64.zip -DestinationPath ap-windows-amd64 + Expand-Archive -Path ap-windows--v0.9.1.zip -DestinationPath . ``` + Extracting the archive creates a folder of the same name that contains `ap.exe`. + **Step 2: Move the binary to a bin directory** ```powershell New-Item -ItemType Directory -Force -Path "$HOME\bin" - Move-Item ap-windows-amd64\ap.exe "$HOME\bin\ap.exe" + Move-Item ap-windows--v0.9.1\ap.exe "$HOME\bin\ap.exe" ``` **Step 3: Add to PATH** @@ -88,7 +92,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies **Step 5: Verify the installation** ```powershell - ap --version + ap version ``` ## Configure the Build File diff --git a/en/mkdocs.yml b/en/mkdocs.yml index 773c21319f..426f169427 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -354,6 +354,7 @@ nav: - Policies: - Overview: api-gateway/next/policies/overview.md - Policy execution order: api-gateway/next/policies/policy-execution-order.md + - Add or Update Policies: api-gateway/next/policies/add-or-update-policies.md - Custom Policies: - Writing a Custom Policy: api-gateway/next/policies/custom-policies/writing-a-custom-policy.md - Building Gateway with Custom Policies: api-gateway/next/policies/custom-policies/building-gateway-with-custom-policies.md @@ -427,6 +428,7 @@ nav: - Policies: - Overview: api-gateway/1.2.0/policies/overview.md - Policy execution order: api-gateway/1.2.0/policies/policy-execution-order.md + - Add or Update Policies: api-gateway/1.2.0/policies/add-or-update-policies.md - Custom Policies: - Writing a Custom Policy: api-gateway/1.2.0/policies/custom-policies/writing-a-custom-policy.md - Building Gateway with Custom Policies: api-gateway/1.2.0/policies/custom-policies/building-gateway-with-custom-policies.md @@ -497,6 +499,7 @@ nav: - Policies: - Overview: api-gateway/1.1.0/policies/overview.md - Policy execution order: api-gateway/1.1.0/policies/policy-execution-order.md + - Add or Update Policies: api-gateway/1.1.0/policies/add-or-update-policies.md - Custom Policies: - Writing a Custom Policy: api-gateway/1.1.0/policies/custom-policies/writing-a-custom-policy.md - Building Gateway with Custom Policies: api-gateway/1.1.0/policies/custom-policies/building-gateway-with-custom-policies.md @@ -566,6 +569,7 @@ nav: - Policies: - Overview: api-gateway/1.0.0/policies/overview.md - Policy execution order: api-gateway/1.0.0/policies/policy-execution-order.md + - Add or Update Policies: api-gateway/1.0.0/policies/add-or-update-policies.md - Custom Policies: - Writing a Custom Policy: api-gateway/1.0.0/policies/custom-policies/writing-a-custom-policy.md - Building Gateway with Custom Policies: api-gateway/1.0.0/policies/custom-policies/building-gateway-with-custom-policies.md @@ -1502,6 +1506,7 @@ plugins: api-gateway/observability/tracing/overview.md: api-gateway/1.1.0/observability/tracing/overview.md api-gateway/observability/tracing/viewing-traces-in-jaeger.md: api-gateway/1.1.0/observability/tracing/viewing-traces-in-jaeger.md api-gateway/overview.md: api-gateway/1.1.0/overview.md + api-gateway/policies/add-or-update-policies.md: api-gateway/1.2.0/policies/add-or-update-policies.md api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md: api-gateway/1.1.0/policies/custom-policies/building-gateway-with-custom-policies.md api-gateway/policies/custom-policies/writing-a-custom-policy.md: api-gateway/1.1.0/policies/custom-policies/writing-a-custom-policy.md api-gateway/policies/overview.md: api-gateway/1.1.0/policies/overview.md