NGF: Add guardrails doc by bjee19 · Pull Request #2191 · nginx/documentation

bjee19 · 2026-08-07T23:48:56Z

Add document for NGF's integration with F5 AI Guardrails.

Checklist

Before sharing this pull request, I completed the following checklist:

I read the Contributing guidelines
My branch adheres to the Git conventions
My content changes adhere to the F5 Technical Writing Style Guide
If my changes involve potentially sensitive information¹, I have assessed the possible impact
I have waited to ensure my changes pass tests, and addressed any discovered issues

Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content. ↩

mjang

Some of my comments depend on whether / where we refer to F5 AI Guardrails or NGF guardrails

mjang · 2026-08-10T13:47:16Z

+
+## Before you begin
+
+You need an F5 AI Guardrails API endpoint to inspect payloads. This can be an F5 hosted service or a service running inside your cluster.


We have many F5 AI Guardrails API endpoints

I think the right endpoint might be: https://docs.aisecurity.f5.com/operations/get_prompts.html ?

Oh yea those are endpoints/paths on a specific F5 AI Guardrails service. I guess I was talking about the F5 AI Guardrails service. such as us1.calypsoai.app / eu1.calypsoai.app, or a self hosted endpoint.

When a doc says:

"You need an F5 AI Guardrails API endpoint to inspect payloads."

I think: "Which endpoint"? I made my best guess.

Oh yea those are endpoints/paths on a specific F5 AI Guardrails service. I guess I was talking about the F5 AI Guardrails service. such as us1.calypsoai.app / eu1.calypsoai.app, or a self hosted endpoint.

As you can see from the link, you can include the server in the URL. The (changeable) default shown in the AI Security API doc is us1.calypsoai.app.

So do you think I should give the example us1.calypsoai.app to help clarify what endpoint means?

because that endpoint can be different per user. they should/would know the answer to "which endpoint?"

Actually the base URL depends on the deployment -- which varies per customer (not user?)

us1.calypsoai.app or eu1.calypsoai.app would correspond to a SaaS install. For on prem, the base URL depends on the deploying customer. Ref: https://docs.aisecurity.f5.com/integrations/_base_vars.html

Sorry yea the base url can vary per customer, how would you suggest this portion be changed to account for that?

I differentiate between BASE_URL and endpoint.

BASE_URL = something like us1.calypsoai.app

Endpoint = what's added to the end of the BASE_URL

Based on what I see, I'm guessing it's based on the scans endpoint

With examples such as https://docs.aisecurity.f5.com/api-docs/scan-request-streaming.html#scan-a-request-body-before-you-send-it

Suggested change

You need an F5 AI Guardrails API endpoint to inspect payloads. This can be an F5 hosted service or a service running inside your cluster.

To inspect payloads, you can use the F5 AI Guardrails [scans](https://docs.aisecurity.f5.com/operations/get_scans.html) endpoint. Specifically, this can be an F5 hosted service or a service running inside your cluster.

With the `scans/` endpoint, the server URL varies depending on whether you've deployed AI Security on your system, or use the AI Security SaaS deployment. For more information, see our description of [BASE_VARS](https://docs.aisecurity.f5.com/integrations/_base_vars.html).

Yea, though currently NGF doesn't allow for any other endpoint besides the scans endpoint. We don't allow the user to configure any endpoint and it almost feels like an implementation detail that is unnecessary to bring up.

I'd rather hide that part of the implementation and perhaps add a small line just saying something like "NGINX Gateway Fabric uses the scans/ endpoint when communicating with the F5 AI Guardrails API for both requests and responses (and link to the docs just so they can look into it if they want)" than insinuate that the user can configure this endpoint.

mjang · 2026-08-10T13:52:36Z

+The `cluster.local` suffix in the in-cluster URL is the cluster's DNS domain. If your cluster uses a different domain, configure it with the `--cluster-domain` flag on the NGINX Gateway Fabric controller (default: `cluster.local`).
+{{< /call-out >}}
+
+For an external backend, create an `ExternalName` Service pointing at your hosted Guardrails API:


Question: with the Guardrails API, are we referring to some F5 API? (That may change some of my comments)

If it isn't an F5 API, we need to figure out how to clarify:

What's a NGF guardrail

What's used for F5 AI Guardrails

Guardrails API is referring to this product https://docs.aisecurity.f5.com/api-docs/getting-started-defend.html. and this https://docs.aisecurity.f5.com/api-docs/prompts-scans.html.

There is no NGF guardrails.

But in that section I don't put the full "F5 AI Guardrails" because they are self-hosted, meaning they aren't sending requests to https://us1.calypsoai.app/, they are sending to their own hosted version of F5 AI Guardrails. I can adjust if necessary.

I've added a suggstion earlier (and will add one for the end of the page)

mjang

I've suggested a few other changes. Thanks for clarifying how NGF integrates

mjang · 2026-08-10T21:12:01Z

+
+## Before you begin
+
+You need an F5 AI Guardrails API endpoint to inspect payloads. This can be an F5 hosted service or a service running inside your cluster.


I differentiate between BASE_URL and endpoint.

BASE_URL = something like us1.calypsoai.app

Endpoint = what's added to the end of the BASE_URL

Based on what I see, I'm guessing it's based on the scans endpoint

With examples such as https://docs.aisecurity.f5.com/api-docs/scan-request-streaming.html#scan-a-request-body-before-you-send-it

Suggested change

You need an F5 AI Guardrails API endpoint to inspect payloads. This can be an F5 hosted service or a service running inside your cluster.

To inspect payloads, you can use the F5 AI Guardrails [scans](https://docs.aisecurity.f5.com/operations/get_scans.html) endpoint. Specifically, this can be an F5 hosted service or a service running inside your cluster.

With the `scans/` endpoint, the server URL varies depending on whether you've deployed AI Security on your system, or use the AI Security SaaS deployment. For more information, see our description of [BASE_VARS](https://docs.aisecurity.f5.com/integrations/_base_vars.html).

mjang · 2026-08-10T21:15:32Z

+
+- **Prompts** — the client's *input* is inspected before it reaches the LLM. A block returns `403` with `error.type: invalid_request_error`.
+- **Responses** — the model's *output* is inspected before it reaches the client. A block returns `403` with `error.type: api_error`.
+


I'm thinking (uncertain)

Suggested change

You can set up prompts and responses as described in [Scan streaming](https://docs.aisecurity.f5.com/api-docs/scan-request-streaming.html), in our AI Security documentation.

mjang · 2026-08-10T21:31:34Z

+The `cluster.local` suffix in the in-cluster URL is the cluster's DNS domain. If your cluster uses a different domain, configure it with the `--cluster-domain` flag on the NGINX Gateway Fabric controller (default: `cluster.local`).
+{{< /call-out >}}
+
+For an external backend, create an `ExternalName` Service pointing at your hosted Guardrails API:


I've added a suggstion earlier (and will add one for the end of the page)

mjang · 2026-08-10T21:35:21Z

I'm going to follow up with the AI Security PM on Tuesday Aug 11 (we have a weekly meeting).

bjee19 added 2 commits August 7, 2026 16:47

Add guardrails doc

e7d94ae

Use document IP address

5fcfe96

bjee19 requested a review from a team as a code owner August 7, 2026 23:48

github-actions Bot added documentation Improvements or additions to documentation product/ngf Issues related to NGINX Gateway Fabric labels Aug 7, 2026

bjee19 requested a review from a team August 7, 2026 23:49

mjang reviewed Aug 10, 2026

View reviewed changes

Add suggested fixes

e6ebd7d

mjang reviewed Aug 10, 2026

View reviewed changes

Small fix to further reading link

4fd0da3


		## Before you begin

		You need an F5 AI Guardrails API endpoint to inspect payloads. This can be an F5 hosted service or a service running inside your cluster.

-You need an F5 AI Guardrails API endpoint to inspect payloads. This can be an F5 hosted service or a service running inside your cluster.
+To inspect payloads, you can use the F5 AI Guardrails [scans](https://docs.aisecurity.f5.com/operations/get_scans.html) endpoint. Specifically, this can be an F5 hosted service or a service running inside your cluster.
+With the `scans/` endpoint, the server URL varies depending on whether you've deployed AI Security on your system, or use the AI Security SaaS deployment. For more information, see our description of [BASE_VARS](https://docs.aisecurity.f5.com/integrations/_base_vars.html).


		- Prompts — the client's input is inspected before it reaches the LLM. A block returns `403` with `error.type: invalid_request_error`.
		- Responses — the model's output is inspected before it reaches the client. A block returns `403` with `error.type: api_error`.



	You can set up prompts and responses as described in [Scan streaming](https://docs.aisecurity.f5.com/api-docs/scan-request-streaming.html), in our AI Security documentation.

Uh oh!

Conversation

bjee19 commented Aug 7, 2026

Checklist

Footnotes

Uh oh!

mjang left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mjang left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mjang commented Aug 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants